Table Of ContentROM Kernel Reference Manual:
Includes and Autodocs
'
Third Edition
Commodore-Amiga, Incorporated
AMIGA TECHNICAL REFERENCE SERIES
....
TT
Addison-Wesley Publishing Company, Inc.
Reading, Massachusetts Menlo Park, California New York
Don Mills, Ontario Wokingham, England Amsterdam Bonn
Sydney Singapore Tokyo Madrid San Juan
Paris Seoul Milan Mexico City Taipei
Contributors:
Steve Beats, Dave Berezowski, Ray Brand, Robert Burns, Peter Chema, Eric Cotton, Sam Dicker, Andy Finkel, Darren Greenwald,
William Hawes, Larry Hildebrand, Randell Jesup, Neil Katin, Kevin Klop, Bill Koester, Dale Larson, Dale Luck, Jim Mackraz,
R.J. Mica!, Bryce Nesbitt, Bob Pariseau, Rob Peck, Torn Pohorsky, Carl Sassenrath, Carolyn Scheppner, Spencer Shanson,
Stan Shepard, Mike Sinz, and Bart Whiteb ook.
Book production and editing:
Dan Baker
Cover designer:
Hannus Design Associates
C language cross reference:
John Toebes and Doug Walker with SAS C Development System 5.10 .11.
'
Copyright© 1991 by Commodore Electronics Limited.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where th~e designations appear in this book and
Addison-Wesley was aware of a trademark claim, the designations have been printed In Initial caps. Amiga, Amiga 500, Amiga 1000, Amiga 2000, and Amiga 3000 are registered
trademark of Commodore-Amiga, Inc. AmigaDOS, Workbench, and Kickstart are trademarks of Commodore-Amiga, Inc. AUTOCONFIG is a trademark of Commodore Elec
tronics Ltmited. 68000, 68010, 68020, 68030, 68040, and Motorola are trademarks of Motorola, Inc. ARexx is a trademark of WIShful Thinking Development Corp. Commodore
and the Commodore logo are registered trademarks of Commodore Electronics Ltmited. ADAPTAlphacom Is a registered trademark and Alphapro Is trademark of Alphacom,
Inc. Aztec C and Manx are trademarks of Manx Software Systems. Brother Is a registered trademark of Brother Industries, Ltd. Canon Is a registered trademark of Canon USA,
Inc. CAPE and Inovatronics are trademarks of lnovatronics, Inc. Centronics is a registered trademark of Centronics Data Computer Corp. ColorMaster is a trademark of Cal
Camp. Diablo Is a registered trademark of Xerox Corporation. Epson Is registered trademark of Epson America, Inc. Hlsoft and Devpac Amiga are trademarks of !liSe ft. IBM
Is a registered trademark and Proprinter Is a trademark of International Business Machines Corp. Imagewritcr and Apple II are trademarks of Apple Computer, Inc. Laserjet
and Palntjet are trademarks of the Hewlett Packard Company. Lattice Is a registered trademark of Lattice, Inc. LetterPro 20 Is a trademark of Qume Corporation. NEC is a ~'<'gis
tered trademark of NEC Information Systems. Okidata Is a registered trademark of Okldata, a division of Oki America, Inc. Okimate 20 is a trademark of Okidata, a division of
Oki America, Inc. Pinwriter Is a registered trademark of NEC Information Systems. UNIX is a registered trademark of AT&T.
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanica~ photocopy
ing,. recording, or othenvise, without the prior written permission of the publisher. Printed Ln the United States of America. Published simultaneously in Canada.
Commodore item number: 327271-07
1 2 3 4 5 6 7 8 9 10 AL 9594939291
First printing, May 1991
ISBN 0-201-56m-3
WARNING: The information described in this manual may contain errors or bugs, and may not function as described. All information is subject to enhancement or upgrade for
any reason including to fix bugs, add features, or change performance. As with all software upgrades, full compatibility, although a goal, cannot be guaranteed, and is in fact
unlikely.
DISCLAIMER: COMMODORE-AMIGA, INC., ("COMMODORE") MAKES NO WARRANTIES, EI'IHER EXPRESSED OR IMPLIED, OR REPESE1\TATIONS WJ'll! RESPECT
10 THE INFORMATION DESCRIBED HEREIN. SUCH INFORMATION IS PROVIDED ON AN "AS IS" BASIS AND IS EXPRESSLY SUBJECT lD CHANCE WITHOUT
NOTICE. IN NO EVENT WILL COMMODORE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTI:\'G FROM ANY
CLAIM ARISING OUT OF TilE INFORMATION PRESENTED HEREIN, EVEN IF IT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DA.\IAGF.S. SOME STATES DO
NOT ALLOW 1HE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES OR UABILITIES FOR INCIDENTAL OR CONSEQUFNITAL DAMAGES, SO THE ABOVE
LIMITATION OR EXCLUSION MAY NOT APPLY.
CONTENTS
Introduction ................................................................................................................ 1
Library Autodocs ................................................................................................... 11
asl.library 16
commodities .library 21
cx_lib.library 35
diskfont.library 43
dos.library 47
exec .library 126
expansion.library 182
gadtools.library 193
graphics.library 205
icon .library 273
iffparse.library 280
intuition.library 303
keyrnap.library 375
layers.library 378
mathieeedoubbas.library 393
mathieeedoubtrans.library 400
mathieeesingbas.library 409
mathieeesingtrans.library 416
mathtrans.library 425
rexxsyslib.library 434
translator.library 440
utility.library 441
workbench.library 455
Device Autodocs ............................................................................................... 459
audio.device 462
clipboard. device 473
console.device 477
gameport.device 485
input. device 488
keyboard.device 493
narrator. device 497
parallel.device 503
printer. device 509
serial. device 521
timer.device 530
trackdisk.device 536
Resource Autodocs .......................................................................................... 547
battclock.resource 550
ba ttmem.resource 552
cia.resource 555
disk.resource 558
FileSystem.resource 562
misc.resource 563
potgo.resource 565
Linker Library Autodocs .............................................................................. 567
amiga.library 570
debug.library 581
amiga.library source code 585
C Language Include Files (.h) 589
Clib 590
Devices 616
Dos 638
Graphics 667
Hardware 685
Libraries 721
Resources 741
Rexx 748
Utility 753
Workbench 755
Assembly Language Include Files (.i) 759
Devices 760
Dos 783
Exec 797
Graphics 817
Hardware 833
Intuition 839
Libraries 866
Resources 883
Rexx 890
Utility 896
Workbench 898
Reference Charts 901
Function Offsets 902
Structure Reference 913
C Language Cross Reference 924
Amiga Function Index 996
Introduction
About this book
The Arniga Technical Reference Series is the official guide to programming Commodore's Amiga
computers. This volume, the Amiga ROM Kernel Reference Manual: Includes and Autodocs, contains
alphabetically organized Autodoc function summaries and listings of the Arniga system include files.
Autodocs are descriptions of the Arniga's system functions. The include files list the Amiga's system
definitions and data structures. This revised edition has been updated for Release 2 of the Arniga
operating system.
This manual is the essential quick reference for all Amiga programmers. It contains:
0 Summaries of the system library functions
0 Summaries of the system device commands
0 Summaries of system resource calls
0 Summaries of the amiga.lib functions and source code
0 C language include files (.h files)
0 Assembly language include files (.i files)
0 Handy charts designed to ease debugging and exploring
The other manuals in this series are the Amiga User Interface Style Guide, the Amiga ROM Kernel
Reference Manual: Libraries, the Amiga ROM Kernel Reference Manual: Devices, and the Amiga Hardware
Reference Manual.
1
About the examples
Except as noted, 68000 assembly language examples have been assembled under the Innovatronics CAPE
assembler V2.x, the HiSoft Devpac assembler Vl.2, and the Lake Forest Logic ADAPT assembler 1.0. No
substantial changes should be required to switch between assemblers.
C examples have been compiled under SAS C, version 5.10a and Manx Aztec C 68K, version S.Od.
Default compiler options are used in both cases. All the C examples assume that the automatic Ctrl-C
feature of the compiler has been disabled. Add this code to each example to complete it:
For SAS C (and Lattice C revisions 4.0 and greater)
Compile with: lc -L <filename>.c
I* Add this function before main(). This overrides the default
* Lattice CTRL-C trap. If this function returns zero, then the
* CTRL-C event will be ignored *I
int CXBRK ( void ) return(O);
int chkabort( void return(O);
For Aztec C
Compile with: cc <filename>. c
ln <filename.o> -lc
I* Add this near the top *I
finclude <functions.h>
I* Add this before main() *I
extern int Enable_Abort; I* reference abort enable *I
I* Add this after main(), as the first active line in the program *I
Enable_Abort=O; I* turn off CTRL-C *I
2
General Amigo development guidelines
The environment of the Amiga computer is quite different than that of many other systems. The Amiga is
a multitasking platform, which means multiple programs can run on a single machine simultaneously.
However, for multitasking to work correctly, care must be taken to ensure that programs do not interfere
with one another. It also means that certain guidelines must be followed during programming.
0 Check for memory loss. Operate your program, then exit. Write down the amount of free memory.
Repeat the operation of your program and exit. The amount of free memory remaining should be
exactly the same. Any difference indicates a serious problem in your cleanup. (Beware when
checking the amount of free memory -some memory loss is normal the first time you open a
device or disk-based library because the system has to allocate memory to accommodate them.
That is why you should run the program once before checking free memory.)
0 Use all of the program debugging and stress tools that are available when writing and testing your
code. New debugging tools such as Enforcer, MungWall, and Scratch can help find uninitialized
pointers, attempted use of freed memory and misuse of scratch registers or condition codes (even
in programs that appear to work perfectly).
0 Always make sure you actually get any system resource that you ask for. This applies to memory,
windows, screens, file handles, libraries, devices, ports, etc. Where an error value or return is
possible, ensure that there is a reasonable failure path. Many poorly written programs will
appear to be reliable, until some error condition (such as memory full or a disk problem) causes
the program to continue with an invalid or null pointer, or branch to untested error handling
code.
0 Always clean up after yourself. This applies for both normal program exit and program termination
due to error conditions. Anything that was opened must be closed, anything allocated must be
deallocated. It is generally correct to do closes and deallocations in reverse order of the opens
and allocations. Be sure to check your development language manual and startup code; some
items may be closed or deallocated automatically for you, especially in abort conditions. If you
write in the C language, make sure your code handles Ctrl-C properly.
3
0 Remember that memory, peripheral configurations, and ROMs differ between models and between
individual systems. Do not make assumptions about memory address ranges, storage device
names, or the locations of system structures or code. Never call ROM routines directly. Beware
of any example code you find that calls routines at addresses in the $FOOOOO-$FFFFFF range.
These are ROM routines and they will move with every OS release. The only supported interface
to system ROM code is through the library, device, and resource calls.
0 Never assume library bases or structures will exist at any particular memory location. The only
absolute address in the system is $00000004, which contains a pointer to the exec.library base.
Do not modify or depend on the format of private system structures. This includes the poking of
copper lists, memory lists, and library bases.
0 Never assume that programs can access hardware resources directly. Most hardware is controlled
by system software that will not respond well to interference from other programs. Shared
hardware requires programs to use the proper sharing protocols. Use the defined interface; it is
the best way to ensure that your software will continue to operate on future models of the Amiga.
0 Never access shared data structures directly without the proper mutual exclusion (locking).
Remember that other tasks may be accessing the same structures.
0 The system does not monitor the size of a program's stack. Take care that your program does not
cause stack overflow, and provide enough extra stack space for the possibility that future
revisions of system functions might require additional stack space.
0 Never use a polling loop to test signal bits. If your program waits for external events like menu
selection or keystrokes, do not bog down the multitasking system by busy-waiting in a loop.
Instead, let your task go to sleep by Wait()ing on its signal bits. For example:
signals= (ULONG)Wait( (l<<windowPtr->UserPort->mp_SigBit)
(l<<consoleMsgPortPtr->mp_SigBit) );
This turns the signal bit number for each port into a mask, then combines them as the argument
for the exec.library /Wait() function. When your task wakes up, handle all of the messages at
each port where the SigBit is set. There may be more than one message per port, or no messages
at the port. Make sure that you ReplyMsg() to all messages that are not replies themselves. If
you have no signal bits to Wait() on, use Delay() or WaitTOFO to provide a measured delay.
4
