AmigaDOS Data Structures

Process Data Structures

These values are created as part of an AmigaDOS process; there is a complete set for each process.

A process is an Exec task with a number of extra data structures appended. The process structure consists of:

• Exec task structure
• Exec message port
• AmigaDOS process value

The process identifier AmigaDOS uses internally is a pointer to the Exec message port (pr_MessagePort) from which the Exec task may be obtained.

AmigaDOS process values are as follows:

Type	Name	Description
BPTR	pr_SegList	Array of seg lists used by this process
LONG	pr_StackSize	Size of process stack in bytes
APTR	pr_GlobVec	Global vector for this process (BCPL)
LONG	pr_TaskNum	CLI task number of zero if not a CLI
BPTR	pr_StackBase	Ptr to high memory end of process stack
LONG	pr_Result2	Value of secondary result from last call
BPTR	pr_CurrentDir	Lock associated with current directory
BPTR	pr_CIS	Current CLI Input Stream
BPTR	pr_COS	Current CLI Output Stream
APTR	pr_ConsoleTask	Console handler process for current window
APTR	pr_FileSystemTask	File handler process for current drive
BPTR	pr_CLI	Pointer to CLI
APTR	pr_ReturnAdd	Pointer to previous stack frame
APTR	pr_PktWait	Function to be called when awaiting msg
APTR	pr_WindowPtr	Window for error printing
BPTR	pr_HomeDir	Home directory of executing program
LONG	pr_Flags	Flags telling DOS about process
LONG	(*pr_ExitCode)(LONG returncode, LONG pr_ExitData)	Code to call on exit of program or NULL
LONG	pr_ExitData	Passed as an argument to pr_ExitCode
UBYTE*	pr_Arguments	Arguments passed to the process at start
struct MinList	pr_LocalVars	Local environment variables
ULONG	pr_ShellPrivate	For the use of the current Shell
BPTR	pr_CES	Error stream - if NULL, use pr_COS

To identify the segments that a particular process uses, you must use pr_SegList. pr_SegList is an array of longwords with its size in Seg_List[0]. Other elements are either zero or a BPTR to a SegList. CreateProc() and CreateNewProc() create this array with the first two elements of the array pointing to resident code and the third element, being the SegList, passed an argument. When a process terminates, FreeMem() is used to return the space for the pr_SegList.

The pr_StackSize field indicates the size of the process stack, as supplied by the user when calling CreateProc() or CreateNewProc(). Note that the process stack is not the same as the command stack a CLI uses when it calls a program. The CLI obtains its command stack just before it runs a program and you may alter the size of this stack with the STACK command. When you create a process, AmigaDOS obtains the process stack and stores the size in pr_StackSize. The pointer to the space for the process control block and the stack is also stored in the MemEntry field of the task structure. When the process terminates this space is returned via a call to FreeVec(). You can also chain any memory you obtain into this list structure so that it, too, gets put back when the task terminates. But be careful, this method won't work for a program run from the CLI since memory is not freed until the process goes away.

If a call to CreateProc() or CreateNewProc() creates the process, GlobVec is a pointer to the Shared Global Vector. However, some internal handler processes use a private global vector.

The value of pr_TaskNum is normally zero; a CLI process stores the small integer that identifies the invocation of the CLI here.

The pointer pr_StackBase points to the high-memory end of the process stack. This is the end of the stack when using languages such as C or assembler; it is the base of the stack for languages such as BCPL. Note that pr_StackBase may not be the same as the one your application uses (eg. if your program is started from the CLI).

The pr_Result2 and pr_CurrentDir fields are handled by the AmigaDOS functions IoErr() and CurrentDir(), respectively. pr_CIS and pr_COS are the values Input() and Output() return and refer to the filehandles you should use when running a program under the CLI. Never access pr_CIS and pr_COS directly. Instead use the AmigaDOS functions provided for this purpose.

The pr_ConsoleTask field refers to the console handler for the current window. The pr_FileSystemTask field refers to the file handler for the boot device. You use these values when attempting to open the * device or file by a relative path name when pr_CurrentDir is null.

The pr_CLI pointer is nonzero only for CLI processes. In this case it refers to a further structure the CLI uses with the following format:

Type	Name	Description
LONG	cli_Result2	Value of IOErr from last command
BSTR	cli_SetName	Name of current directory
BPTR	cli_CommandDir	BPTR to CLI path
LONG	cli_ReturnCode	Return code from last command
BSTR	cli_CommandName	Name of current command
LONG	cli_FailLevel	Fail level (set by FAILAT)
BSTR	cli_Prompt	Current prompt (set by PROMPT)
BPTR	cli_StandardInput	Default (terminal) CLI input
BPTR	cli_CurrentInput	Current CLI input
BSTR	cli_CommandFile	Name of EXECUTE command file
LONG	cli_Interactive	Boolean; TRUE if prompts required
LONG	cli_Background	Boolean; TRUE if CLI created by RUN
BPTR	cli_CurrentOutput	Current CLI output
LONG	cli_DefaultStack	Stack size to be obtained in longwords
BPTR	cli_StandardOutput	Default (terminal) CLI output
BPTR	cli_Module	SegList of currently loaded command

The exit() function uses the value of pr_ReturnAddr which points to just above the return address on the currently active stack. If a program exits by performing an RTS on an empty stack, the control passes to the code address pushed onto the stack by CreateProc() or by the CLI. If a program terminates with a call to Exit(), then AmigaDOS uses this pointer to extract the same return address. Note that the AmigaDOS function Exit() is inappropriate for most programs which should use the exit() function provided by the compiler manufacturer instead.

The value of pr_PktWait is normally zero. If it is nonzero, then AmigaDOS calls pr_PktWait whenever a process is about to go to sleep to await a signal indicating that a message has arrived. In the same way as GetMsg(), the function should return a message when one is available. Usually you use this function to filter out any private messages arriving at the standard process message port that are not intended for AmigaDOS.

The value of pr_WindowPtr is used when AmigaDOS detects an error that normally requires the user to take some action. Examples of these errors are attempting to write to a write-protected disk, or when the disk is full. If the value of pr_WindowPtr is -1, then the error is returned to the calling program as an error code from the AmigaDOS call of Open(), Write(), or whatever. If the value is zero, then AmigaDOS places a request box on the Workbench screen informing the user of the error and providing the opportunity to retry the operation or to cancel it. If the user selects to cancel, then AmigaDOS returns the error code to the calling program. If the user selects retry, or insert[s] a disk, then AmigaDOS attempts the operation once more. Under V2.0 and later versions of AmigaDOS, if a pr_WindowPtr is zero then AmigaDOS will put requesters on the default public screen.

If you put a positive value into the pr_Window field, then AmigaDOS takes this to be a pointer to a window structure. Normally you would place the Window structure of the window you are currently using here. In this case, AmigaDOS displays the error message within the window you have specified, rather than using the Workbench screen. You can always leave the pr_WindowPtr field as zero, but if you are using another screen, then the messages AmigaDOS displays appear on the Workbench screen, possibly obscured by your own screen.

The initial value of pr_WindowPtr is inherited from the process that created the current one. If you decide to alter pr_WindowPtr from within a program that runs under the CLI, then you must save the original value and restore it when you finish; otherwise, the CLI process contains a pr_WindowPtr that refers to a window that is no longer present.

The rest of the fields in the process structure are brand new and appear only in V2.0 and later versions of AmigaDOS. The pr_HomeDir field is the directory from which the program associated with this process was loaded. This field is referenced when the PROGDIR: feature of V2.0 is used. The pr_Flags field is a private field containing flags for AmigaDOS.

The field named (*pr_ExitCode)() is a LONG pointing to the cleanup code to be called after the program exits. It takes as a parameter the return code of the program and may return a modified return code when the process terminates. The pr_ExitData is provided as a convenience and allows you to pass additional information to your pr_ExitCode automatically.

Another new field is pr_Arguments. This is a null terminated string of the register level arguments passed to the process when the program was started. You can modify this field using the SetArguments() function but if you do, you must restore it to its original value before exiting.

pr_LocalVars is used to implement process local variables. Do not access these directly. Use the new calls GetVar(), SetVar(), and DeleteVar() instead.

The pr_ShellPrivate field is for the private use of the Shell associated with this process. Never access it.

The value in pr_CES points to an error stream to use for this process separate from pr_CIS and pr_COS. This field is not fully implemented in AmigaDOS at the time of this writing.

Redirecting System Requesters

On the Amiga, when a user or a program requests a file on a volume that is not currently mounted, AmigaDOS brings up a system request on the Workbench screen asking the user to insert the disk.

The pr_WindowPtr field of the Process structure determines where most process-related system requesters appear. The normal value is 0L which causes the requesters to come up on the Workbench screen (the default public screen).

If your application has its own custom screen, and you perform any actions that might cause a system request (such as loading of files or printing) you should redirect such requesters for your Process so that the requesters related to your Process are brought up on your application screen.

To do this, first find your Process:

proc = (struct Process *) FindTask(NULL);

Save the old value of proc->pr_WindowPtr, and replace it with a pointer to one of the Intuition windows on your custom screen. The requesters will come up on the same screen (and with the same title as) that window. Be sure to replace the original pr_WindowPtr value before closing your window or exiting your program.

Other applications may wish to temporarily disable such requesters so that attempts to Open() or Lock() unmounted volumes simply return an error without bringing up a requester. To do this, save the old value of pr_WindowPtr and store -1L there instead. Before exiting your program, replace the original value of pr_WindowPtr.

DOS Library Structure

This data structure only exists once; however, all AmigaDOS processes use it. If you make a call to OpenLibrary(), you can obtain the library base pointer. The base of the data structure is a positive offset from the library base pointer. The library base pointer points to the following structure:

   Library Node structure
   APTR to DOS RootNode
   APTR to DOS Shared Global Vector
   DOS private register dump

Many internal AmigaDOS calls use the Shared Global Vector, which is a jump table. You should not normally use it, except through the supplied interface calls, as it is liable to change without warning.

The RootNode structure is as follows:

Type	Name	Description
BPTR	rn_TaskArray	Array of CLI processes
BPTR	rn_ConsoleSegment	SegList for the CLI
struct DateStampe	rn_Time	Current time
LONG	rn_RestartSeg	SegList for the disk validator process
BPTR	rn_Info	Pointer to the Info structure
BPTR	rn_FileHandlerSegment	Segment for a file handler
struct MinList	rn_CliList	New list of all CLI processes; the first cpl_Array is also rn_TaskArray
struct MsgPort*	rn_BootProc	Private pointer to msgport of boot filesystem
BPTR	rn_ShellSegment	SegList for Shell (for NEWSHELL)
LONG	rn_Flags	DOS flags

The rn_TaskArray is an array with its size stored in rn_TaskArray[0]. The process ID (in other words the MsgPort associated with the process) for each CLI is stored in the array. The process ID for CLI n is stored in rn_TaskArray[n]. An empty slot is filled with zero. Under AmigaDOS 2.0, TaskArray is duplicated and extended with the rn_CliList structure. The commands RUN and NEWCLI scan the rn_TaskArray table for the next free slot and use this for the CLI created. You should not access the TaskArray table directly from your code. Instead use the AmigaDOS functions provided for this purpose.

The rn_ConsoleSegment is the SegList for the code of the CLI. RUN and NEWCLI use this value to create a new instance of a CLI.

The RootNode stores the current date and time; normally you should use the AmigaDOS function DateStamp() to return a consistent set of values. The values Days, Mins, and Ticks specify the date and time. The value of Days is the number of days since January 1st, 1978. The value of Mins is the number of minutes since midnight. A tick is one-fiftieth of a second, but the time is only updated anytime DateStamp() is called.

The RestartSeg is the SegList for the code of the disk validator, which is a process that AmigaDOS creates whenever you insert a new disk into a drive. In V2.0 and later versions of AmigaDOS this field is null since the disk validator process is no longer separate.

The rest of the fields in the RootNode structure are brand new and appear only in V2.0 and later versions of AmigaDOS.

The field named rn_FileHandlerSegment is a seglist of the ROM filesystem.

The rn_CliList field is a list of tables of CLI pointers. This supplants [the] rn_TaskArray method used in previous versions of AmigaDOS and eliminates the limit on the number of CLIs that can run at the same time. Note that the first table in the rn_CliList is also stored in TaskArray for the sake of backwards compatibility. This list should be accessed using FindCli() and MaxCli() only. Do not directly access it from your code.

The rn_BootProc field is a private pointer to the filesystem process that the system was booted off of. This is not necessarily the same as the ROM filesystem.

The rn_ShellSegment field is the SegList for the boot Shell and rn_Flags contains new flags used by AmigaDOS for future expansion. Currently it contains only one flag which determines whether * or #? is used as the AmigaDOS wildcard.

Info Substructure

To access the Info substructure with the following format, you use the rn_Info pointer.

Type	Name	Descrption
BPTR	di_McName	Pointer to the resident list
BPTR	di_DevInfo	Device list
BPTR	di_Devices	Currently zero
BPTR	di_Handlers	Currently zero
APTR	di_NetHand	Currently zero

Most of the fields in the Info substructure are empty at this time, and Commodore-Amiga will use them for expanding the system.

The DevInfo structure is a linked list. You use it to identify all the device names that AmigaDOS knows about; this includes ASSIGN names and disk volume tnames. To access the information in the DevInfo structure under V1.3 and earlier versions of AmigaDOS, you must first call Forbid(). This means no Wait() calls or message passing are allowed while you access the structure (and you must alo call Permit() when you are finished).

In V2.0 and later versions of AmigaDOS you must call LockDosList() before accessing the DevInfo structure. This allows you to call Wait() and do message passing in the code that accesses DevInfo. You must call UnLockDosList() when you are finished. For compatibility with V1.3 programs, LockDosList() calls Forbid() and UnLockDosList() calls Permit(). However, this will be removed in a future release of AmigaDOS.

There are three possible formats for the linked list entries in DevInfo depending on whether the entry refers to a disk volume, an assign, or a device or directory. For an entry describing a device or directory (via ASSIGN) the entry is as follows: