GEMDOS Master Document

GEMDOS Function Reference

Cauxin()

	Cauxin() waits for the next available data byte from GEMDOS handle 2 (normally device 'aux:') and when available, returns it in the low byte of the returned WORD.

Opcode	3 (0x03)

Availability	All GEMDOS versions.

Binding	move.w #$3,-(sp) trap #1 addq.l #2,sp

Return Value	The WORD value contains the retrieved byte in the lower eight bits. The contents of the upper 8 bits are currently undefined.

Caveats	This function can cause flow control problems.When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.In addition, if this handle is redirected to something other than 'aux:', an end-of-file will hang the system. Besides these known bugs, this function is used by many 'C' compilers to redirect standard error messages. It is therefore advisable to use Bconin() instead.

See Also	Cauxis(), Cauxout(), Bconin()

Cauxis()

WORD Cauxis( VOID )

	Cauxis() indicates whether GEMDOS handle 2 (normally device 'aux:') has at least one character waiting.

Opcode	18 (0x12)

Availability	All GEMDOS versions.

Binding	move.w #$12,-(sp) trap #1 addq.l #2,sp

Return Value	The return value will be DEV_READY (-1) if at least one character is available for reading or DEV_BUSY (0) if not.

Caveats	When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.In addition, some 'C' compilers use this handle as a standard error device. It is therefore advisable to use Bconstat().

See Also	Cauxin(), Cauxout(), Cauxos(), Bconstat()

Cauxos()

WORD Cauxos( VOID )

	Cauxos() indicated whether GEMDOS handle 2 (normally device 'aux:') is ready to receive characters.

Opcode	19 (0x13)

Availability	All GEMDOS versions

Binding	move.w #$13,-(sp) trap #1 addq.l #2,sp

Return Value	A value of DEV_READY (-1) is returned if the output device is ready to receive characters or DEV_BUSY (0) if it is not.

Caveats	This function actually returns the status of whatever device GEMDOS handle 2 is redirected to. In addition, some 'C' compilers use this handle as a standard error device. It is therefore recommended that Bcostat() be used instead.

See Also	Cauxin(), Cauxis(), Cauxout(), Bcostat().

Cauxout()

VOID Cauxout( ch )

WORD ch;

	Cauxout() outputs a character to GEMDOS handle 2, normally the 'aux:' device.

Opcode	4 (0x04)

Availability	All GEMDOS versions.

Parameters	ch is a WORD value, however, only the lower eight bits are sent. The upper eight bits must be 0.

Binding	move.w #ch,-(sp) move.w #4,-(sp) trap #1 addq.l #4,sp

Caveats	This function can cause flow control to fail when GEMDOS handle 2 is directed to 'aux:'.In addition, some 'C' compilers use this function as a standard error device. It is therefore recommended that Bconout() be used in place of this function.

See Also	Cauxin(), Cauxis(), Cauxos(), Bconout()

Cconin()

LONG Cconin( VOID )

	Cconin() reads a character (waiting until one is available) from GEMDOS handle 0 (normally 'con:').

Opcode	1 (0x01)

Availability	All GEMDOS versions.

Binding	move.w #1,-(sp) trap #1 addq.l #2,sp

Return Value	The LONG value returned is a bit array arranged as follows:

		Bits 31-24	Bits 23-16	Bits 15-8	Bits 7-0
		Shift key status(see below)	Keyboard scancode	Unused (0)	ASCII code of character

	The ASCII code of the character will be 0 if a non-ascii keyboard key is struck.

Caveats	When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.

Comments	The shift key status will only be returned when bit 3 of the system variable conterm (char *(0x484)) is set. This is normally not enabled.If the handle has been redirected, the inputted character will appear in the lower 8 bits of the return value.

See Also	Cconis(), Cconout(), Cconrs(), Cnecin(), Crawin(), Bconin()

Cconis()

WORD Cconis( VOID )

	Cconis() verifies that a character is waiting to be read from GEMDOS handle 0 (normally 'con:').

Opcode	11 (0xB)

Availability	All GEMDOS versions.

Binding	move.w #$0B,-(sp) trap #1 addq.l #2,sp

Return Value	Cconis() returns a DEV_READY (-1) if a character is available or DEV_BUSY (0) if not.

See Also	Cconin(), Bconstat()

Cconos()

WORD Cconos( VOID )

	Cconos() checks to see whether a character may be output to GEMDOS handle 1 (normally 'con:').

Opcode	16 (0x10)

Availability	All GEMDOS versions.

Binding	move.w #$10,-(sp) trap #1 addq.l #2,sp

Return Value	This function returns DEV_READY (-1) if at least one character may be sent or DEV_BUSY (0) if not.

See Also	Cconout(), Bcostat()

Cconout()

VOID Cconout( ch )

WORD ch;

	Cconout() outputs one character via GEMDOS handle 1 (normally 'con:').

Opcode	2 (0x02)

Availability	All GEMDOS versions.

Parameters	ch is a WORD value, however, only the lower eight bits are sent through the output stream. The upper eight bits must be 0.

Binding	move.w ch,-(sp) move.w #2,-(sp) trap #1 addq.l #4,sp

Caveats	With GEMDOS versions below 0.15, this handle should not be redirected to a write-only device as the call attempts to read from the output stream to process special keys.

Comments	No line feed translation is done at the time of output. To start a new line, ASCII 13 and ASCII 10 must both be sent.

See Also	Cconin(), Bconout()

Cconrs()

VOID Cconrs( str )

char *str;

	Cconrs() reads a string from the standard input stream (GEMDOS handle 0) and echoes it to the standard output stream (GEMDOS handle 1).

Opcode	10 (0x0A)

Availability	All GEMDOS versions.

Parameters	str should be a character pointer large enough to hold the inputted string. On function entry, str[0] should be equal to the maximum number of characters to read.

Binding	pea str move.w #$0A,-(sp) trap #1 addq.l #6,sp

Return Value	On return, the string buffer passed as a parameter will be filled in with the inputted characters. str[1] will contain the actual number of characters in the buffer. (char ) &str[2]* is the pointer to the start of the actual string in memory.Cconrs() will not terminate unless ctrl-c is pressed, the buffer is full or either return or ctrl-j is pressed.

Caveats	GEMDOS versions below 0.15 echoes the input to the console even if output has been redirected elsewhere.

Comments	The string Cconrs() creates is not null-terminated. The following keys are processed by the function:

		Key	Translation
		return	End of input. Do not place RETURN in in buffer.
		ctrl-j	End of line. Do not place CTRL-J in buffer.
		ctrl-h	Kill last character.
		delete	Kill last character.
		ctrl-u	Echo input line and start over.
		ctrl-x	Kill input line and start over.
		ctrl-r	Echo input line and continue.
		ctrl-c	Exit program.

	When the input stream is redirected, Cconrs() returns 0 in str[1] when the end-of-file marker is reached.

See Also	Cconin(), Cconws()

Cconws()

WORD Cconws( str )

char *str; Cconws() returns a WORD conatining the number of characters output or 0 if an error occurred.

	Cconws() writes a string to GEMDOS handle 1 (normally 'con:').

Opcode	9 (0x09)

Availability	All GEMDOS versions.

Parameters	str is a pointer to a null-terminated character string to be written to the output stream.

Binding	pea str move.w #$09,-(sp) trap #1 addq.l #6,sp

Caveats	With GEMDOS versions below 0.15, this handle should not be redirected to a write-only device as the call attempts to read from the output stream to process special keys.

Comments	No line feed translation is performed on outputted characters so both an ASCII 13 and ASCII 10 must be sent to force a new line. In addition, the system checks for special keys so a ctrl-c embedded in the string will terminate the process.

See Also	Cconout(), Cconrs()

Cnecin()

LONG Cnecin( VOID )

	Cnecin() is exactly the same as Cconin() except that the character fetched from the input stream is not echoed.

Opcode	8 (0x08)

Availability	All GEMDOS versions.

Parameters	None.

Binding	move.w #8,-(sp) trap #1 addq.l #2,sp

Return Value	The LONG value returned is a bit array arranged as follows:

		Bits 31-24	Bits 23-16	Bits 15-8	Bits 7-0
		Shift key status(see below)	Keyboard scancode	Unused (0)	ASCII code of character

	The ASCII code of the character will be 0 if a non-ascii keyboard key is struck.

Caveats	When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.

Comments	The shift key status will only be returned when bit 3 of the system variable conterm (char *(0x484)) is set. This is normally not enabled.If the handle has been redirected, the inputted character will appear in the lower 8 bits of the return value.

See Also	Cconin(), Bconin()

Cprnos()

WORD Cprnos( VOID )

	Cprnos() returns the status of GEMDOS handle 3 (normally 'prn:').

Opcode	17 (0x11)

Availability	All GEMDOS versions.

Parameters	None.

Binding	move.w #$11,-(sp) trap #1 addq.l #2,sp

Return Value	Cprnos() returns a DEV_READY (-1) if the output stream is ready to receive a character or DEV_BUSY (0) if not.

See Also	Cprnout(), Bcostat()

Cprnout()

WORD Cprnout( ch )

WORD ch;

	Cprnout() sends one character to GEMDOS handle 3 (normally 'prn:').

Opcode	5 (0x05)

Availability	All GEMDOS versions.

Parameters	ch is a WORD value, however, only the lower 8 bits are sent to the output stream. The upper eight bits should be 0.

Binding	move.w ch,-(sp) move.w #$5,-(sp) trap #1 addq.l #4,sp

Return Value	Cprnout() returns a non-zero value if the function successfully wrote the character to the printer or 0 otherwise.

Comments	No input translation is performed with this call. Therefore, you must send an ASCII 13 and ASCII 10 to force a new line.

See Also	Bconout()

Crawcin()

LONG Crawcin( VOID )

	Crawcin() is similar to Cconout(), however it does not process any special keys and does not echo the inputted character.

Opcode	7 (0x07)

Availability	All GEMDOS versions.

Binding	move.w #$07,-(sp) trap #1 addq.l #2,sp

Return Value	The LONG value returned is a bit array arranged as follows:

		Bits 31-24	Bits 23-16	Bits 15-8	Bits 7-0
		Shift key status(see below)	Keyboard scancode	Unused (0)	ASCII code of character

	The ASCII code of the character will be 0 if a non-ascii keyboard key is struck.

Caveats	When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.

Comments	The shift key status will only be returned when bit 3 of the system variable conterm (char (0x484)) is set. This is normally not enabled.If the handle has been redirected, the inputted character will appear in the lower 8 bits of the return value.Under normal circumstances, when GEMDOS* handle 0 is being read from, no special system keys, including ctrl-c, are checked.

See Also	Cconin(), Crawio(), Bconin()

Crawio()

LONG Crawio( ch )

WORD ch;

	Crawio() combines console input and output in one function.

Opcode	6 (0x06)

Availability	All GEMDOS versions.

Parameters	ch is a WORD value, however, only the lower eight bits are meaningful and the upper eight bits should be set to 0. If ch is 0x00FF on input, Crawio() returns the character read from GEMDOS handle 0 (normally 'con:').

Binding	move.w ch,-(sp) move.w #6,-(sp) trap #1 addq.l #4,sp

Return Value	If ch is 0x00FF upon entry, Crawio() returns a bit array arranged as follows:

		Bits 31-24	Bits 23-16	Bits 15-8	Bits 7-0
		Shift key status(see below)	Keyboard scancode	Unused (0)	ASCII code of character

	The ASCII code of the character will be 0 if a non-ascii keyboard key is struck. If no character was waiting in the input stream, Crawio() returns a 0.

Caveats	When using this function while its handle is redirected, an end-of-file condition will hang the system. GEMDOS version 0.30 and all MiNT versions correct this bug. MiNT returns MINT_EOF (0xFF1A) when the end-of-file is reached.Due to the definition of this call it is impossible to write 0x00FF to the output stream or read a zero from this call.

Comments	The shift key status will only be returned when bit 3 of the system variable conterm (char (0x484)) is set. This is normally not enabled.If the handle has been redirected, the inputted character will appear in the lower 8 bits of the return value.Under normal circumstances, when GEMDOS* handle 0 is being read from, no special system keys, including ctrl-c, are checked.

See Also	Cconout(), Cconin(), Bconout(), Bconin()

Dclosedir()

LONG Dclosedir( dirhandle )

LONG dirhandle;

	Dclosedir() closes the specified directory.

Opcode	299 (0x12B)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	dirhandle is a valid directory handle which specifies the directory to close.

Binding	move.l dirhandle,-(sp) move.w #$12B,-(sp) trap #1 addq.l #6,sp

Return Value	Dclosedir() returns E_OK (0) if successful or EIHNDL (37) if the directory handle was invalid.

See Also	Dopendir(), Dreaddir(), Drewinddir()

Dcntl()

LONG Dcntl( cmd, name, arg )

WORD cmd;

char *name;

LONG arg;

	Dcntl() performs file system specific operations on directories or files.

Opcode	304 (0x130)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	The only two built-in file systems that support Dcntl() calls are 'U:\' and 'U:\DEV.' cmd specifies what operation to perform and affects the meaning of name and arg. Valid cmd arguments for 'U:\' are

	cmd	Meaning
	FS_INSTALL (0xF001)	This mode installs a new file system. name must be 'U:\' and arg should point to a fs_descr structure as follows: struct fs_descr { FILESYS file_system; WORD dev_no; LONG flags; LONG reserved[4]; }; If this call is successful, a pointer to a kerinfo* structure is returned, otherwise the return value is NULL. The file system itself is not accessible until this call is made and it is mounted with FS_MOUNT.
	FS_MOUNT (0xF002)	This mode mounts an instance of an installed file system. name should be in the format 'U:\???' where '???' is the name which the file system will be accessed by. arg should point to the fs_descr structure as above. If the file system is mounted correctly, the dev_no field will be updated to reflect the instance number of the mount (file systems may be mounted multiple times).
	FS_UNMOUNT (0xF003)	This mode unmounts an instance of a file system. name is the name of the file system in the form 'U:\???' where '???' is the name of the file system instance. arg should point to the file system fs_descr structure.
	FS_UNINSTALL (0xF004)	This mode uninstalls a file system identified by the fs_descr structure passed in arg. A file system can only be sucessfully uninstalled after all instances of it have been unmounted. name should be 'U:\'.

	Valid cmd arguments for 'U:\DEV' are:

	cmd	Meaning
	DEV_INSTALL (0xDE02)	This command attempts to install a device driver. name should be in the format 'U:\DEV\???' where '???' is the name of the device to install. arg is a pointer to a dev_descr structure as follows: struct dev_descr { /* Pointer to a device driver structure / DEVDRV driver; /* Placed in aux field of file cookies / WORD dinfo; / 0 or O_TTY (0x2000) for TTY / WORD flags; / If O_TTY is set, points to tty struct / struct tty tty; /* Reserved for future expansion / LONG reserved[4]; }If the device is successfully installed, Dcntl()* will return a pointer to a kerinfo structure which contains information about the kernel. On failure, Dcntl() will return NULL. See the section on loadable file systems earlier in this chapter for more information.
	DEV_NEWTTY (0xDE00)	This command identifies a BIOS terminal device whose name is name (in the form 'U:\DEV\DEVNAME' and whose device number is arg. This call simply makes the MiNT kernel aware of the device. It should have been previously installed by Bconmap(). Any attempt to access the device prior to installing it with the BIOS will result in an EUNDEV (-15) unknown device error. If the device is installed, Dcntl() returns a 0 or positive value. A negative return code signifies failure.
	DEV_NEWBIOS (0xDE01)	This command is the same as DEV_NEWTTY except that it is designed for devices which must have their data transmitted raw (SCSI devices, for example).

Binding	move.l arg,-(sp) pea name move.w cmd,-(sp) move.w #$130,-(sp) trap #1 lea 12(sp),sp

Version Notes	The FS_ group of cmd arguments are only available as of MiNT version 1.08.Due to a bug in MiNT versions 1.08 and below, calling this function with a parameter of DEV_NEWBIOS will not have any effect.

Return Value	See above.

See Also	Bconmap(), Fcntl()

Dcreate()

LONG Dcreate( path )

char *path;

	Dcreate() creates a GEMDOS directory on the specified drive.

Opcode	57 (0x39)

Availability	All GEMDOS versions.

Parameters	path is a pointer to a string containing the directory specification of the directory to create. path should not contain a trailing backslash. Below are some examples and their results.

	path	Result
	C:\ONE\ATARI	Creates a folder named "ATARI" as a subdirectory of "ONE" on drive 'C:'.
	\ONE\ATARI	Creates a folder named "ATARI" as a subdirectory of "ONE" on the current GEMDOS drive.
	ATARI	Creates a folder named "ATARI" as a subdirectory of the current GEMDOS path on the current GEMDOS drive.

Binding	pea path move.w #$39,-(sp) trap #1 addq.l #6,sp

Return Value	Upon return one of three codes may result: E_OK (0) : Operation successful EPTHNF (-34): Path not found EACCDN (-36): Access denied

Caveats	Prior to GEMDOS version 0.15 GEMDOS did not detect if the creation of a subdirectory failed and could therefore leave partially created directories on disk.

See Also	Ddelete()

Ddelete()

LONG Ddelete( path )

char *path;

	Ddelete() removes a directory on the specified drive.

Opcode	58 (0x3A)

Availability	All GEMDOS versions.

Parameters	path contains the directory specification of the directory you wish to remove. path should not contain a trailing backslash. For valid examples of path, see the entry for Dcreate().

Binding	pea path move.w #$3A,-(sp) trap #1 addq.l #6,sp

Return Value	Upon return one of four codes may result: E_OK (0) : Operation successful EPTHNF (-34): Path not found EACCDN (-36): Access denied EINTRN (-65): Internal error

Caveats	Prior to GEMDOS version 0.15 a Ddelete() on a directory recently created will fail but a second attempt will not.

Comments	The directory being deleted must be empty or the call will fail.

See Also	Dcreate()

Dfree()

LONG Dfree( buf, drive )

DISKINFO *buf;

WORD drive;

	Dfree() returns information regarding the storage capacity/current usage of the specified drive.

Opcode	54 (0x36)

Availability	All GEMDOS versions.

Parameters	buf is a DISKINFO pointer which will be filled in on function exit. DISKINFO is defined as:

	typedef struct { /* No. of Free Clusters / ULONG b_free; / Clusters per Drive / ULONG b_total; / Bytes per Sector / ULONG b_secsize; / Sectors per Cluster */ ULONG b_clsize; } DISKINFO;

	drive is a WORD which indicates the drive to perform the operation on. A value of DEFAULT_DRIVE (0) indicates the current GEMDOS drive. A value of 1 indicates drive 'A:', a 2 indicates 'B:', etc...

Binding	move.w drive,-(sp) pea buf move.w #$36,-(sp) trap #1 addq.l #8,sp

Return Value	Upon return, a value of 0 indicates success. Otherwise, a negative GEMDOS error code is returned.

Caveats	Prior to GEMDOS version 0.15 this function is very slow when used on a hard disk.

Comments	To obtain the free number of bytes on a disk, use the formula (info.b_free * info.b_secsize * info.b_clsize). To obtain the total number of bytes available on a disk, use the formula (info.b_total * info.b_secsize * info.b_clsize).

Dgetcwd()

LONG Dgetcwd( size, drv, path )

char *path;

WORD drv, size;

	Dgetcwd() returns the processes' current working directory for the specified drive.

Opcode	315 (0x13B)

Availability	Available when a 'MiNT' cookie with a version of at least 0.96 exists.

Parameters	path is a pointer to a buffer with room for at least size characters into which will be copied the complete working path of drive drv.

Binding	pea path move.w size,-(sp) move.w drv,-(sp) move.w #$13B,-(sp) trap #1 lea 10(sp),sp

Return Value	Dgetcwd() returns 0 if successful or a GEMDOS error code otherwise.

See Also	Dgetpath(), Dgetdrv()

Dgetdrv()

WORD Dgetdrv( VOID )

	Dgetdrv() returns the current GEMDOS drive code.

Opcode	25 (0x19)

Availability	All GEMDOS versions.

Binding	move.w #$19,-(sp) trap #1 addq.l #2,sp

Return Value	Dgetdrv() returns the current GEMDOS drive code. Drive 'A:' is represented by a return value of 0, 'B:' by a return value of 1, and so on.

See Also	Dsetdrv()

Dgetpath()

LONG Dgetpath( buf, drive )

char *buf;

WORD drive;

	Dgetpath() returns the current GEMDOS path specification.

Opcode	71 (0x47)

Availability	All GEMDOS versions.

Parameters	buf is a pointer to a character buffer which will contain the current GEMDOS path specification on function exit. drive is the number of the drive whose path you want returned. drive should be DEFAULT_DRIVE (0) for the current GEMDOS drive, 1 for drive 'A:', 2 for drive 'B:', and so on.

Binding	move.w drive,-(sp) pea buf move.w #47,-(sp) trap #1 addq.l #6,sp

Return Value	Dgetpath() will return one of two errors on function exit: E_OK (0): Operation successful EDRIVE (-49): Invalid drive specification

Comments	As there is no way to specify the buffer size to this function you should allow at least 128 bytes of buffer space. This will allow for up to 8 folders deep. Newer file systems (CD-ROM drives) may demand up to 200 bytes.

See Also	Dsetpath()

Dlock()

LONG Dlock( mode, drv )

WORD mode, drv;

	Dlock() locks a BIOS disk device against GEMDOS usage.

Opcode	309 (0x135)

Availability	Available when a 'MiNT' cookie with a version of at least 0.93 exists.

Parameters	Setting mode to DRV_LOCK (1) places a lock on BIOS device drv whereas a mode setting of DRV_UNLOCK (0) unlocks drv.

Binding	move.w drv,-(sp) move.w mode,-(sp) move.w #$135,-(sp) trap #1 addq.l #6,sp

Return Value	Dlock() returns 0 if successful or a negative GEMDOS error code otherwise.

Comments	Locking a device provides a method for device formatters to prevent other processes from simultaneously attempting to access a drive. If a process which locked a device terminates, that device is automatically unlocked.BIOS device numbers and GEMDOS drive letters do not necessarily have a one to one correspondence. To lock a GEMDOS drive use Fxattr() to determine the device number of the drive you wish to lock.

See Also	Fxattr()

Dopendir()

LONG Dopendir( name, flag )

char *name;

WORD flag;

	Dopendir() opens the specified directory for reading.

Opcode	296 (0x128)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	name is a pointer to a null-terminated directory specification of the directory to open. name should not be contain a trailing backslash.flag determines whether to open the file in normal or compatibility mode. A value of MODE_NORMAL (0) for flag signifies normal mode whereas a value of MODE_COMPAT (1) signifies compatibility mode.Compatibility mode forces directory searches to be performed much like Fsfirst() and Fsnext() (restricting filenames to the DOS 8 + 3 standard in uppercase). In normal mode, filenames returned by Dreaddir() will be in the format native to the file system and a UNIX style file index will be returned.

Binding	move.w flag,-(sp) pea name move.w #$128,-(sp) trap #1 addq.l #8,sp

Return Value	Dopendir() returns a LONG directory handle (which may be positive or negative) if successful. A negative GEMDOS error code will be returned if the call fails.

Caveats	Failure to properly close directory handles may cause the system to eventually run out of handles which will cause the OS to fail.

Comments	Negative directory handles and negative GEMDOS error codes may be differentiated by checking for 0xFF in the high byte. Returned values with 0xFF in the high byte are errors.

See Also	Dclosedir(), Dreaddir(), Drewinddir()

Dpathconf()

LONG Dpathconf( name, mode )

char *name;

WORD mode;

	Dpathconf() returns information regarding limits and capabilities of an installed file system.

Opcode	292 (0x124)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	name specifies the file system you wish information about. mode dictates the return value as follows:

	Name	mode	Return Value
	DP_INQUIRE	-1	Returns the maximum legal value for the mode parameter in Dpathconf().
	DP_IOPEN	0	Retuns the possible maximum number of open files at one time. If UNLIMITED (0x7FFFFFFF) is returned, then the number of open files is limited only by available memory.
	DP_MAXLINKS	1	Returns the maximum number of links to a file. If UNLIMITED (0x7FFFFFFF) is returned, then the number of links to a file is limited only by available memory.
	DP_PATHMAX	2	Returns the maximum length of a full path name in bytes. If UNLIMITED (0x7FFFFFFF) is returned, then the maximum size of a pathname is unlimited.
	DP_NAMEMAX	3	Returns the maximum length of a file name in bytes. If UNLIMITED (0x7FFFFFFF) is returned, then the maximum length of a filename is unlimited.
	DP_ATOMIC	4	Returns the number of bytes that can be written per write operation. If UNLIMITED (0x7FFFFFFF) is returned, then the number of bytes that can be written at once is limited only by available memory.
	DP_TRUNC	5	Returns a code indicating the type of filename truncation as follows:DP_NOTRUNC (0)File names are not truncated. If a file name in any system call exceeds the filename size limit then an ERANGE (-64) range error is returned.DP_AUTOTRUNC (1)File names are truncated automatically to the maximum allowable length.DP_DOSTRUNC (2)File names are truncated to the DOS standard (maximum 8 character node with 3 character extension).
	DP_CASE	6	Returns a code which indicates case sensitivity as follows:DP_SENSITIVE (0)File system is case-sensitive. DP_NOSENSITIVE (1)File system is not case-sensitive (file and path names are always converted to upper-case).DP_SAVEONLY (2)File system is not case-sensitive, however, file and path names are saved in their original case. Ex: A file called 'Compendi.um' will appear as 'Compendi.um' but may be referenced as 'compendi.um' or 'COMPENDI.UM'.

Binding	move.w mode,-(sp) pea name move.w #$124,-(sp) trap #1 addq.l #8,sp

Return Value	See above.

See Also	Sysconf()

Dreaddir()

LONG Dreaddir( len, dirhandle, buf )

WORD len;

LONG dirhandle;

char *buf;

	Dreaddir() enumerates the contents of the specified directory.

Opcode	297 (0x129)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	Dreaddir() fetches information about the next file contained in the directory specified by dirhandle. len specifies the length of the buffer pointed to by buf which should be enough to hold the size of the filename, NULL byte, and index (if in normal mode).

Binding	pea buf move.l dirhandle move.w len move.w #$129,-(sp) trap #1 lea 12(sp),sp

Return Value	Dreaddir() returns a 0 if the operation was successful, ERANGE (-64) if the buffer was not large enough to hold the index and name, or ENMFIL (-47) if there were no more files to read.

Comments	In normal mode, Dreaddir() returns a 4-byte file index in the first four bytes of buf. The filename then follows starting at the fifth byte of buf. The file index is present to prevent confusion under some file systems when two files of the same name exist. In some file systems this is legal, however, in all file systems, the 4-byte index will be unique.When in compatibility mode, the filename begins at &buf[0].

See Also	Dopendir(), Dclosedir(), Drewinddir()

Drewinddir()

LONG Drewinddir( handle )

LONG handle;

	Drewinddir() rewinds the specified directory pointer to its first file.

Opcode	298 (0x12A)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	handle specifies the directory handle of the directory to rewind.

Binding	move.l handle,-(sp) move.w #$12A,-(sp) trap #1 addq.l #6,sp

Return Value	Drewinddir() returns a 0 if successful or a negative GEMDOS error code otherwise.

See Also	Dopendir(), Dreaddir(), Drewinddir()

Dsetdrv()

LONG Dsetdrv( drive )

WORD drive;

	Dsetdrv() sets the current GEMDOS drive and returns a bitmap of mounted drives.

Opcode	14 (0x0E)

Availability	All GEMDOS versions.

Parameters	drive is the code of the drive to set as the default GEMDOS disk drive. Calling the function as: bmap = Dsetdrv(Dgetdrv());will return the bitmap of mounted drives without changing the current GEMDOS drive.

Binding	move.w drive,-(sp) move.w #$0E,-(sp) trap #1 addq.l #4,sp

Return Value	Dsetdrv() returns a LONG bit array that indicates which drives are mounted on the system. Bit 0 indicates drive 'A:', bit 1 drive 'B:', etc.

See Also	Dgetdrv()

Dsetpath()

LONG Dsetpath( path )

char *path;

	Dsetpath() sets the path of the current GEMDOS drive.

Opcode	59 (0x3B)

Availability	All GEMDOS versions.

Parameters	path is a pointer to a character buffer containing the new path specification for the current GEMDOS drive.

Binding	pea path move.w #$3B,-(sp) trap #1 addq.l #6,sp

Return Value	Dsetpath() returns one of two return codes on function exit: E_OK (0): Operation successful EPTHNF (-34): Path not found

Caveats	You may specify a drive letter and colon in the input path specification to set the path of a particular drive but this feature is unstable in all versions of GEMDOS and may confuse drive assignments. It is therefore advised that this feature be avoided.

See Also	Dgetpath()

Fattrib()

LONG Fattrib( fname, flag, attr )

char *fname;

WORD flag, attr;

	Fattrib() reads or modifies the attribute bits of a GEMDOS file.

Opcode	67 (0x43)

Availability	All GEMDOS versions.

Parameters	fname is a pointer to a null-terminated string which contains the GEMDOS filename of the file to manipulate. flag should be set to FA_INQUIRE (0) to read the file's attributes and FA_SET (1) to set them. If you are setting attributes, attr contains the file's new attributes.

Binding	move.w attr,-(sp) move.w flag,-(sp) pea fname move.w #$43,-(sp) trap #1 lea 10(sp),sp

Return Value	If reading the attributes, Fattrib() returns a bit array of attributes as defined below. If setting the attributes, Fattrib() returns the file's old attributes. In any case, a negative return code indicates that a GEMDOS error occurred.

		Name	Bit	Meaning
		FA_READONLY	0	Read-only flag
		FA_HIDDEN	1	Hidden file flag
		FA_SYSTEM	2	System file flag
		FA_VOLUME	3	Volume label flag
		FA_DIR	4	Subdirectory
		FA_ARCHIVE	5	Archive flag
		-	6...	Currently reserved

Caveats	GEMDOS versions below 0.15 did not set the archive bit correctly. The archive bit is now correctly set by TOS when a file is created or written to.

Fchmod()

LONG Fchmod( name, mode )

char *name;

WORD mode;

	Fchmod() alters file access permissions of the named file.

Opcode	306 (0x132)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	name specifies a valid GEMDOS file specification of the file whose access permissions you wish to modify. mode is a bit mask composed by OR'ing together values defined as follows:

	Name	Mask	Meaning
	S_IRUSR	0x100	Read permission for the owner of the file.
	S_IWUSR	0x80	Write permission for the owner of the file.
	S_IXUSR	0x40	Execute permission for the owner of the file.
	S_IRGRP	0x20	Read permission for members of the same group the file belongs to.
	S_IWGRP	0x10	Write permission for members of the same group the file belongs to.
	S_IXGRP	0x08	Execute permission for members of the same group the file belongs to.
	S_IROTH	0x04	Read permission for all others.
	S_IWOTH	0x02	Write permission for all others.
	S_IXOTH	0x01	Execute permission for all others.

Binding	move.w mode,-(sp) pea name move.w #$132,-(sp) trap #1 addq.l #8,sp

Return Value	Fchmod() returns E_OK (0) if successful or a negative GEMDOS error code otherwise.

Caveats	Not all file systems support all bits. Unrecognized bits will be ignored.

Comments	Only the owner of a file may change a file's permission status.'Execute' status refers to the permission to search the named directory for a file name or component.

See Also	Fattrib(), Fxattr()

Fchown()

LONG Fchown( name, uid, gid )

char *name;

WORD uid, gid;

	Fchown() changes a file's ownership.

Opcode	305 (0x131)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	name specifies the file whose ownership status you wish to change. uid sets the new owner and gid sets the new group.

Binding	move.w gid,-(sp) move.w uid,-(sp) pea name move.w #$131,-(sp) trap #1 lea 10(sp),sp

Return Value	Fchown() returns 0 if the operation was successful or a negative GEMDOS error code otherwise.

Caveats	Most file systems don't understand the concept of file ownership (including TOS).

Comments	uid may only be modifies if the caller's uid is 0. gid may only be changed to the group id of a group the caller belongs to.

See Also	Fchmod(), Fxattr()

Fclose()

LONG Fclose( handle )

WORD handle;

	Fclose() closes the file specified.

Opcode	62 (0x3E)

Availability	All GEMDOS versions.

Parameters	handle is a valid WORD file handle which will be closed as a result of this call.

Binding	move.w handle,-(sp) move.w #$3E,-(sp) trap #1 addq.l #4,sp

Return Value	Fclose() returns E_OK (0) if the file was closed successfully or EIHNDL (-37) if the handle given was invalid.

Caveats	Calling this function with an invalid file handle will crash the system on GEMDOS versions below 0.15. In addition, GEMDOS versions below 0.15 will become confused if you close a standard GEMDOS handle (0-5).

Comments	As of GEMDOS version 0.15, closing a standard GEMDOS handle (0-5) will simply reset it to its default BIOS state.

See Also	Fcreate(), Fopen()

Fcntl()

LONG Fcntl( handle, arg, cmd )

WORD handle;

LONG arg;

WORD cmd;

	Fcntl() performs a command on the specified file.

Opcode	260 (0x104)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	handle specifies the GEMDOS file handle of the file on which the operation specified by cmd will affect. arg varies with each command. Valid commands are:

	cmd	Meaning
	F_DUPFD (0x0000)	Duplicate the given file handle. Fcntl() will return a file handle in the range arg - 32. If no file handles exist within that range, an error will be returned.
	F_GETFD (0x0001)	Return the inheritance flag for the specified file. A value of 1 indicates that child processes started with Pexec() will inherit this file handle, otherwise a value of 0 is returned. arg is ignored.
	F_SETFD (0x0002)	Set the inheritance flag for the named file. arg specifies if child processes started with Pexec() will inherit the file handle. A value of 0 indicates that they will not. A value of 1 indicates that they will. GEMDOS handles 0-5 default to a value of 1whereas other handles default to a value of 0.
	F_GETFL (0x0003)	Return the file descriptor flags for the specified file. These are the same flags passed to Fopen(). arg is ignored.
	F_SETFL (0x0004)	Set the file decriptor flags for the specified file to arg. Only user-modifyable bits are considered. All others should be 0. It is not possible to change a file's read/write mode or sharing modes with this call. Attempts to do this will fail without returning an error code.
	F_GETLK (0x0004)	Test for the presence of a lock on the specified file. arg is a pointer to a FLOCK structure defined as follows: typedef struct flock { /* Type of lock 0 = Read-only lock 1 = Write-only lock 2 = Read/Write lock / WORD l_type; / 0 = offset from beginning of file 1 = offset from current position 2 = offset from end of file / WORD l_whence; / Offset to start of lock / LONG l_start; / Length of lock (0 for rest of file) / LONG l_len; / Process ID maybe filled in by call / WORD l_pid; } FLOCK;If a prior lock exists which would prevent the specified lock from being applied, the interfering lock is copied into the structure with the process ID of the locking process. Otherwise, Fcntl()* returns F_UNLCK (3).
	F_SETLK (0x0005)	Set or remove an advisory lock on the specified file. arg points to a FLOCK structure as defined above.Setting l_type to F_RDLOCK or F_WRLCK will cause a lock to be set. Setting l_type to F_UNLCK wil attempt to remove the specified lock.When locking and unlocking FIFO's, l_whence, l_start, and l_len should be 0.The command returns 0 if successful or a negative GEMDOS error code otherwise.
	F_SETLKW (0x0007)	The calling procedure is the same as above, however, if other processes already have a conflicting lock set, it will suspend the calling process until the lock is freed.
	FSTAT (0x4600)	Get the extended attributes for a file. arg points to a XATTR structure which is filled in with the file's extended attributes. If successful, the function returns 0, otherwise a negative GEMDOS error code is returned. See Fxattr() for an explanation of the XATTR structure.
	FIONREAD (0x4601)	Return an estimate of the number of bytes available for reading from the specified file without causing the process to block (wait for more input) in the LONG pointed to by arg.
	FIONWRITE (0x4602)	Return an estimate of the number of bytes that may be written from the specified file without causing the process to block in the LONG pointed to by arg.
	SHMGETBLK (0x4D00)	Returns the address of a memory block associated with the file. arg should be NULL for future compatibility.Note: Different processes may receive different addresses for a shared block.
	SHMSETBLK (0x4D01)	arg points to a block of memory (previously allocated) which is to be associated with the file. The file must have been created at 'U:\SHM\' or the call will fail.
	PPROCADDR (0x5001)	Return the address of the specified processes' control structure (opened as a file) in arg. See the discussion of MiNT processes for information about this structure.
	PBASEADDR (0x5002)	Return the address of the specified processes' GEMDOS basepage (opened as a file) in arg,
	PCTXTSIZE (0x5003)	Return the length of the specified processes' context structure (opened as a file) in arg. Seeking to the offset returned by PPROCADDR minus this number and reading this many bytes will yield the current user context of the process. Seeking back this many bytes more and reading will yield the last system context of the process. This structure is volatile and is likely to change from one MiNT version to the next.
	PSETFLAGS (0x5004)	arg is a pointer to a LONG from which the processes' memory allocation flags (PRGFLAGS) will be set.
	PGETFLAGS (0x5005)	arg is a pointer to a LONG into which the processes' memory allocation flags (PRGFLAGS) will be placed.
	PTRACEGFLAGS (0x5006)	arg points to a WORD which will be filled in with the trace flags of a process. Setting bit #0 of arg causes the parent process to receive signals destined for the child. See the discussion on program debugging for more information.
	PTRACESFLAGS (0x5007)	arg points to a WORD which will be used to set the trace flags of a process.See the discussion on program debugging for more information.
	PTRACEGO (0x5008)	This call restarts a process which was stopped because of a signal. arg points to a WORD which contains 0 to clear all of the child processes' pending signals or the signal value to send to the process.
	PTRACEFLOW (0x5009)	This call restarts a process in a special tracing mode in which the process is stopped and a SIGTRACE signal is generated whenever program flow changes (ex: JSR/BSR/JMP/BEQ). arg should be set to 0 to clear all of the pending signals of the process being traced or a signal value which is to be sent to the child.
	PTRACESTEP (0x500A)	This call restarts a process and allows it to execute one instruction before a SIGTRAP instruction is generated.
	PLOADINFO (0x500C)	arg points to a structure as follows: struct ploadinfo { WORD fnamelen; char * cmdlin; char * fname; }; cmdlin should point to a 128 byte character buffer into which the processes' command line will be copied.fname should point to a buffer fnamelen bytes long into which the complete path and filename of the process' parent will be copied. If the buffer is too short the call will return ENAMETOOLONG.
	TIOCGETP (0x5400)	Get terminal parameters from the TTY device with the specified file handle. arg is a pointer to an sgttyb structure which is filled in by this command. struct sgttyb { /* Reserved / char sg_ispeed; / Reserved / char sg_ospeed; / Erase character / char sg_erase; / Line kill character / char sg_kill; / Terminal control flags */ WORD sg_flags; };
	TIOCSETP (0x5401)	Set the terminal parameters of the TTY device specified. arg is a pointer to an sgyttb structure as defined above. You should first get the terminal control parameters, modify what you wish to change, and then set them with this call.
	TIOCGETC (0x5402)	Get the terminal control characters of the TTY device specified. arg is a pointer to a tchars structure filled in by this call which is defined as follows: struct tchars { /* Raises SIGINT / char t_intrc; / Raises SIGKILL / char t_quitc; / Starts terminal output / char t_startc; / Stops terminal output / char t_stopc; / Marks end of file / char t_eofc; / Marks end of line */ char t_brkc; };
	TIOCSETC (0x5403)	Set the terminal control characters of the TTY device specified. arg is a pointer to a tchars structure as defined above. Setting any structure element to 0 disables that feature.
	TIOCGLTC (0x5404)	Get the extended terminal control characters from the TTY device specified. arg is a pointer to a ltchars structure which is filled in by this call defined as follows: struct ltchars { /* Raise SIGTSTP now / char t_suspc; / Raise SIGTSTP when read / char t_dsuspc; / Redraws the input line / char t_rprntc; / Flushes output / char t_flushc; / Erases a word / char t_werasc; / Quotes a character */ char t_lnextc; };
	TIOCSLTC (0x5405)	Set the extended terminal control characters for the TTY device specified from the ltchars structure pointed to by arg.
	TIOCGPGRP (0x5406)	Return the process group ID for the TTY specified in the LONG pointed to by arg.
	TIOCSPGRP (0x5407)	Set the process group ID of the TTY specified in the LONG pointed to by arg.
	TIOCSTOP (0x5409)	Stop terminal output (as if the user had pressed ctrl-s). arg is ignored.
	TIOCSTART (0x540A)	Restart output to the terminal (as if the user had pressed ctrl-q) if it had been previously stopped with ctrl-s or a TIOCSTOP command. arg is ignored.
	TIOCGWINSZ (0x540B)	Get information regarding the window for this terminal. arg points to a winsize structure which is filled in by this command. struct winsize { /* # of Text Rows / WORD ws_row; / # of Text Columns / WORD ws_column; / Width of window in pixels / WORD ws_xpixel; / Height of window in pixels */ WORD ws_ypixel; }
	TIOCSWINSZ (0x540C)	Change the extents of the terminal window for the specified TTY. arg points to a winsize structure which contains the new window information. It is up to the window manager to modify the window extents and raise the SIGWINCH signal if necessary.
	TIOCGXKEY (0x540D)	Return the current definition of a system key. arg points to a structure xkey as follows: struct xkey { WORD xk_num; char xk_def[8]; };xk_def will be filled in with the NULL terminated name associated with the key specified in xk_num as follows: xk_num Key 0-9 F1-F10 10-19 F11-F20 20 Cursor up 21 Cursor down 22 Cursor right 23 Cursor left 24 Help 25 Undo 26 Insert 27 Clr/Home 28 Shift+Cursor up 29 Shift+Cursor down 30 Shift+Cursor right 31 Shift+Cursor left
	TIOCSXKEY (0x540E)	Set the current definition of a system key. arg must point to an xkey structure (as defined above). xk_num and xk_def are used to set the text associated with a system key.If a terminal recognizes special keys (by having its XKEY bit set in the sg_flags field of its sgttyb structure) then setting a system key will cause the text specified by xk_def to be sent to a process whenever the key is struck. Note: this works only if the terminal is reading characters using Fread().
	TIOCIBAUD (0x5412)	Read/Write the input baud rate for the specified terminal device. If arg points to a LONG then the input baud rate will be set to that value. If arg is 0, the DTR on the terminal will be dropped (if this feature is supported). If arg is negative, the baud rate will not be changed. The old baud rate is returned in the value pointed to by arg.If the terminal does not support separate input and output baud rates then this call will set both rates.
	TIOCOBAUD (0x5413)	Read/Write the output baud rate for the specified terminal device. If arg points to a LONG then the output baud rate will be set to that value. If arg is 0, the DTR on the terminal will be dropped (if this feature is supported). If arg is negative, the baud rate will not be changed. The old baud rate is returned in the value pointed to by arg.If the terminal does not support separate input and output baud rates then this call will set both rates.
	TIOCCBRK (0x5414)	Clear the break condition on the specified device. arg is ignored.
	TIOCSBRK (0x5415)	Set the break condition on the specified device. arg is ignored.
	TIOCGFLAGS (0x5416)	Return the current stop bit/data bit configuration for the terminal device in the lower 16 bits of the LONG pointed to by arg. See the entry for TIOCSFLAGS for the flags required to parse arg.
	TIOCSFLAGS (0x5417)	Set the current stop bit/data bit configuration for the terminal device. The new configuration is contained in arg. Valid mask values for arg are as follows: Name Mask Meaning TF_1STOP 0x0001 1 stop bit TF_15STOP 0x0002 1.5 stop bits TF_2STOP 0x0003 2 stop bits TF_8BIT 0x0000 8 data bits TF_7BIT 0x0004 7 data bits TF_6BIT 0x0008 6 data bits TF_5BIT 0x000C 5 data bits
	TCURSOFF (0x6300)	Hide the cursor on the selected terminal device. arg is ignored.
	TCURSON (0x6301)	Show the cursor on the selected terminal device. arg is ignored.
	TCURSBLINK (0x6302)	Enable cursor blinking on the selected terminal device. arg is ignored.
	TCURSSTEADY (0x6303)	Disable cursor blinking on the selected terminal device. arg is ignored.
	TCURSSRATE (0x6304)	Set the cursor blink rate to the WORD pointed to by arg.
	TCURSGRATE (0x6305)	Return the current cursor blink rate in the WORD pointed to by arg.

Binding	move.w cmd,-(sp) move.l arg,-(sp) move.w handle,-(sp) move.w #$260,-(sp) trap #1 lea 10(sp),sp

Return Value	Unless otherwise noted, Fcntl() returns a 0 if the operation was successful or a negative GEMDOS error code otherwise.

See Also	Flock(), Fopen(), Fxattr(), Pgetpgrp(), Psetpgrp()

Fcreate()

LONG Fcreate( fname, attr )

char *fname;

WORD attr;

	Fcreate() creates a new file (or truncates an existing one) with the specified name and attributes.

Opcode	60 (0x3C)

Availability	All GEMDOS versions.

Parameters	fname is a character pointer to the GEMDOS file specification of the file to create or truncate. attr is a bit array which specifies the attributes of the new file. Valid mask values are given below:

		Name	Bit	Meaning
		FA_READONLY	0	Read-only file
		FA_HIDDEN	1	Hidden file
		FA_SYSTEM	2	System file
		FA_VOLUME	3	Volume label
		-	4	Reserved
		FA_ARCHIVE	5	Archive bit

Binding	move.w attr,-(sp) pea fname,-(sp) move.w #$3C,-(sp) trap #1 addq.l #8,sp

Return Value	Fcreate() returns a LONG value. If the LONG is negative, it should be interpreted as a GEMDOS error. Possible errors are EPTHNF (-34), ENHNDL (-35) , or EACCDN (36).If positive, the WORD portion of the returned LONG should be regarded as the file handle.

Caveats	With GEMDOS version 0.13, creating a read-only file returns a read-only file handle which is of little use. GEMDOS versions below 0.15 incorrectly allow more than one volume label per disk.

Comments	GEMDOS versions 0.15 and above automatically set the archive bit. You may set it yourself on versions below 0.15.

See Also	Fopen(), Fclose()

Fdatime()

LONG Fdatime( timeptr, handle, flag )

DATETIME *timeptr;

WORD handle, flag;

	Fdatime() reads or modifies a file's time and date stamp.

Opcode	87 (0x57)

Availability	All GEMDOS versions.

Parameters	timeptr is a pointer to a DATETIME structure which is represented below. handle is a valid GEMDOS file handle to the file to modify. flag is FD_INQUIRE (0) to fill timeptr with the file's date/timestamp and FD_SET (1) to change the file's date/timestamp to the contents of timeptr.

	typedef struct { unsigned hour:5; unsigned minute:6; unsigned second:5; unsigned year:7; unsigned month:4; unsigned day:5; } DATETIME;

Binding	move.w flag,-(sp) move.w handle,-(sp) pea timeptr move.w #$57,-(sp) trap #1 lea 10(sp),sp

Return Value	Fdatime() returns a 0 if the date/time was successfully read/modified. Otherwise, it returns a negative GEMDOS error code.

Caveats	GEMDOS versions below 0.15 yielded very unpredictable results with this call and should therefore be avoided.

Comments	timeptr.second should be multiplied times two to obtain the actual value. timeptr.year is expressed as an offset from 1980.

Fdelete()

LONG Fdelete( fname )

char *fname;

	Fdelete() deletes the specified file.

Opcode	65 (0x41)

Availability	All GEMDOS versions.

Parameters	fname is the GEMDOS file specification of the file to be deleted.

Binding	pea fname move.w #$41,-(sp) trap #1 addq.l #6,sp

Return Value	Fdelete() returns E_OK (0) if the operation was successful or a negative GEMDOS error code if it fails.

Caveats	Do not attempt to delete a file that is currently open or unpredictable results will occur.

Comments	Ddelete() must be used to delete subdirectories.

See Also	Ddelete()

Fdup()

LONG Fdup( shandle )

WORD shandle;

	Fdup() duplicates a standard file handle (0-5) and assigns it a new handle (>6).

Opcode	69 (0x45)

Availability	All GEMDOS versions.

Parameters	shandle is the standard GEMDOS handle to be duplicated.

Binding	move.w shandle,-(sp) move.w #$45,-(sp) trap #1 addq.l #4,sp

Return Value	Fdup() returns a normal GEMDOS file handle in the lower WORD of the returned LONG. If the LONG return value is negative then it should be treated as a GEMDOS error code.

Comments	This function is generally used to save a standard file handle so that an Fforce() operation may be undone.

See Also	Fforce()

Fforce()

LONG Fforce( shandle, nhandle )

WORD shandle, nhandle;

	Fforce() is used to redirect the standard input or output from a GEMDOS standard handle to a specific handle created by the application.

Opcode	70 (0x46)

Availability	All GEMDOS versions.

Parameters	shandle is a standard GEMDOS handle to be redirected. nhandle is the new handle you wish to direct it to. Valid values for shandle and nhandle are as follows:

	Name	Handle	GEMDOS Filename	Meaning
	GSH_CONIN	0	con:	Standard input (defaults to whichever BIOS device is mapped to GEMDOS handle -1)
	GSH_CONOUT	1	con:	Standard output (defaults to whichever BIOS device is mapped to GEMDOS handle -1)
	GSH_AUX	2	aux:	Currently mapped serial device (defaults to whichever BIOS device is mapped to GEMDOS handle -2)
	GSH_PRN	3	prn:	Printer port (defaults to whichever BIOS device is currently mapped to GEMDOS handle -3).
	-	4	None	Reserved
	-	5	None	Reserved
	GSH_BIOSCON	-1	None	Refers to BIOS handle 2. This handle may only be redirected under the presence of MiNT. Doing so redirects output of the BIOS.
	GSH_BIOSAUX	-2	None	Refers to BIOS handle 1. This handle may only be redirected under the presence of MiNT. Doing so redirects output of the BIOS.
	GSH_BIOSPRN	-3	None	Refers to BIOS handle 0. This handle may only be redirected under the presence of MiNT. Doing so redirects output of the BIOS.
	GSH_MIDIIN GSH_MIDIOUT	-4 -5	None	GEMDOS handles -4 and 5 refer to MIDI input and output respectively. Redirecting these handles will affect BIOS handle 3. These special handles exist only with the presence of MiNT.

Binding	move.w nhandle,-(sp) move.w shandle,-(sp) move.w #$46,-(sp) trap #1 addq.l #6,sp

Return Value	Fforce() returns E_OK (0) if no error occurred or EIHNDL (-37) if a bad handle is given.

Caveats	Prior to GEMDOS versions 0.15, handles forced to the printer would not work properly.

Comments	This function is often used to redirect the input or output of a child process. It should be used in conjunction with Fdup() to restore the standard handle before process termination. In addition, you should be aware that any file handle redirected to a standard handle ('con:' for example) will be closed when the child exits and should not be closed by the parent.Standard GEMDOS file handles which have been redirected will revert to their original mapping upon Fclose().

See Also	Fdup()

Fgetchar()

LONG Fgetchar( handle, mode )

WORD handle, mode;

	Fgetchar() reads a character from the specified handle.

Opcode	263 (0x107)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	handle is a valid GEMDOS handle to read from. If handle is a TTY then mode (a bit mask) has meaning as follows:

	Name	mode	Meaning
	TTY_COOKED	0x01	Cooked mode. Special control characters such as ctrl-c and ctrl-z are checked and acted upon. In addition, flow control with ctrl-s and ctrl-q is activated.
	TTY_ECHO	0x02	Echo mode. Characters read are echoed back to the TTY.

Binding	move.w mode,-(sp) move.w handle,-(sp) move.w #$107,-(sp) trap #1 addq.l #6,sp

Return Value	Fgetchar() returns the character read in the low byte of the returned LONG. If the device is a terminal where scan codes are available, the LONG will be mapped in the same manner as Bconin(). If an end-of-file is reached, the value 0xFF1A will be returned.

See Also	Bconin(), Fputchar(), Fread()

Fgetdta()

DTA *Fgetdta( VOID )

	Fgetdta() returns current DTA (Disk Transfer Address)

Opcode	47 (0x2F)

Availability	All GEMDOS versions.

Parameters	None.

Binding	move.w #$2F,-(sp) trap #1 addq.l #2,sp

Return Value	Fgetdta() returns a pointer to the current Disk Transfer Address. The structure DTA is defined as: typedef struct { BYTE d_reserved[21]; BYTE d_attrib; UWORD d_time; UWORD d_date; LONG d_length; char d_fname[14]; } DTA;

Comments	When an application starts, its DTA overlaps the command line string in the processes' basepage. Any use of the Fsfirst() or Fsnext() call without first reallocating a new DTA will cause the processes' command line to be corrupted.To prevent this, you should use Fsetdta() to define a new DTA structure for your process prior to using Fsfirst() or Fsnext(). Be careful to avoid assigning your DTA to a local or automatic variable without setting it to its original value before the variable goes out of scope.

See Also	Fsetdta(), Fsfirst(), Fsnext()

Finstat()

LONG Finstat( handle )

WORD handle;

	Finstat() determines the input status of a file.

Opcode	261 (0x105)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	handle specifies the GEMDOS file handle of the file to return information about.

Binding	move.w handle,-(sp) move.w #$105,-(sp) trap #1 addq.l #4,sp

Return Value	Finstat() returns 0 or a positive number of characters waiting to be read if successful. A negative GEMDOS error code is returned otherwise.

Caveats	Currently Finstat() always returns 0 for disk files.

See Also	Cauxis(), Cconis(), Fcntl(), Foutstat()

Flink()

LONG Flink( oldname, newname )

char *oldname, *newname;

	Flink() creates a new name for the specified file. After the call the file may be referred to by either name. An Fdelete() call on one filename will not affect the other.

Opcode	301 (0x12D)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	oldname points to the GEMDOS path specification of the currently existing file and newname specifies the name of the alias to create.

Binding	pea newname pea oldname move.w #$12D,-(sp) trap #1 lea 10(sp),sp

Return Value	Flink() returns a 0 if successful or a negative GEMDOS error code otherwise.

Caveats	Not all file systems support 'hard links'.

Comments	The filenames given must reside on the same physical device.

See Also	Frename(), Fsymlink()

Flock()

LONG Flock( handle, mode, start, length )

WORD handle,mode;

LONG start,length;

	Flock() sets or removes a lock on a portion of a file which prevents other processes from accessing it.

Opcode	92 ($5C)

Availability	Only present when '_FLK' cookie exists.

Parameters	handle specifies the GEMDOS handle of the file. mode is FLK_LOCK (0) to create a lock and FLK_UNLOCK (1) to remove it. start specifies the byte offset from the beginning of the file which indicates where the lock starts. length specifies the length of the lock in bytes.

Binding	move.l length,-(sp) move.l start,-(sp) move.w mode,-(sp) move.w handle,-(sp) trap #1 lea 12(sp),sp

Return Value	Flock() returns E_OK (0) if the call was successful, ELOCKED (-58) if an overlapping section of the file was already locked, ENSLOCK (-59) if a matching lock was not found for removal, or another GEMDOS error code as appropriate.

Comments	To remove a lock, you must specify identical start and length parameters as you originally set.MiNT allows locks to be set on devices by locking their entry in 'U:\DEV\' as shown in the example below: handle = Fopen( "U:\DEV\MODEM1", 3 ); if( handle < 0) return ERR_CODE; /* Unable to open. / retcode = Flock( (WORD)handle, 0, 0, 0 ); / Lock / if( retcode != E_OK ) return FILE_IN_USE; / File is already locked / / * Now do device input/output. / Flock( (WORD)handle, 1, 0, 0 ); / Unlock */ Fclose( (WORD)handle );

See Also	Fopen(), Fwrite(), Fread()

Fmidipipe()

LONG Fmidipipe( pid, in, out )

WORD pid, in, out;

	Fmidipipe() is used to change the file handles used for MIDI input and output.

Opcode	294 (0x126)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	pid is the process id of the process whose MIDI devices you wish to alter. If pid is 0, then the current process will be modified. in specifies the GEMDOS file handle of the device to handle MIDI input. out specifies the GEMDOS file handle of the device to handle MIDI output.

Binding	move.w out,-(sp) move.w in,-(sp) move.w pid,-(sp) move.w #$126,-(sp) trap #1 addq.l #8,sp

Return Value	Fmidipipe() returns a 0 if successful or a negative GEMDOS error code otherwise.

Comments	An Fmidipipe( 0, in, out ) call is essentially the same as: Fforce( -4, in); Fforce( -5, out);After this call, any Bconin() calls to MIDI device 5 will translate to a one character read from handle in. Likewise any Bconout() calls to MIDI device 5 will translate to a one character write to handle out.

See Also	Fdup(), Fforce()

Fopen()

LONG Fopen( fname, mode )

char *fname;

WORD mode;

	Fopen() opens the GEMDOS file specified.

Opcode	61 ($3D)

Availability	All GEMDOS versions. mode bits pertaining to file sharing/record locking are only valid when the '_FLK' cookie is present.

Parameters	fname is the GEMDOS file specification of the file to be opened. mode specifies the mode the file is to be placed into once opened. mode is a bit array which may be formed by using the bit masks given as follows:

		Bit 7			Bits 6-4		Bit 3	Bits 2-0
		Inheritance flag			Sharing mode		Reserved	Access code

	Bits 0-2 specify the file access code as follows:

		Bit 2	Bit 1	Bit 0		File Access Codes
		0	0	0		Read only access (S_READ)
		0	0	1		Write only access (S_WRITE)
		0	1	0		Read/Write access (S_READWRITE)

	Bit 3 is reserved and should always be 0. Bits 4-6 specify the file sharing mode of the file to be opened as follows:

		Bit 6	Bit 5	Bit 4		File Sharing Codes
		0	0	0		Compatibility Mode (S_COMPAT). If the file's read-only bit is set, then this is the same as Deny Writes, otherwise it is the same as Deny Read/Writes.
		0	0	1		Deny Read/Writes (S_DENYREADWRITE)
		0	1	0		Deny Writes (S_DENYWRITE)
		0	1	1		Deny Reads (S_DENYREAD)
		1	0	0		Deny None (S_DENYNONE)

	Bit 7 (S_INHERIT) is the file's inheritance flag. If this flag is not set, a child process will inherit any open file handles and has the same access as the parent. If this flag is set, a child must re-open any files it wishes to use and must face the same sharing restrictions other processes must share.

Binding	move.w mode,-(sp) pea fname move.w #$3D,-(sp) trap #1 addq.l #8,sp

Return Value	Upon return, if the longword is positive, the lower WORD contains the new handle of the open file, otherwise the negative LONG should be regarded as a GEMDOS error code.

Comments	Bits 7-3 of mode should be set to 0 unless the '_FLK' cookie is present indicating the presence of the file sharing/record locking extensions to GEMDOS.

See Also	Fclose(), Fcreate()

Foutstat()

LONG Foutstat( handle )

WORD handle;

	Foutstat() determines the output status of a file.

Opcode	262 (0x106)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	handle specifies the GEMDOS file handle of the file to return information about.

Binding	move.w handle,-(sp) move.w #$106,-(sp) trap #1 addq.l #4,sp

Return Value	Foutstat() returns a 0 or positive number indicating the number of characters which may be written to the specified file without blocking. If an error occurred, Foutstat() returns a negative GEMDOS error code.

Caveats	Currently this function always returns 1 for disk files.

See Also	Cconos(), Cauxos(), Cprnos(), Fcntl(), Finstat()

Fpipe()

LONG Fpipe( fhandle )

WORD fhandle[2];

	Fpipe() creates a pipe named 'SYS$PIPE.xxx' (where 'xxx' is a three digit integer) on 'U:\PIPE\' and returns two file handles to it, one for reading and one for writing.

Opcode	256 (0x100)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	fhandle is a pointer to an array of two WORDs. If the functions is successful, fhandle[0] will contain an open GEMDOS file handle to the pipe which may be used for reading only. fhandle[1] will contain an open GEMDOS file handle to the pipe which may be used for writing only.

Binding	pea fhandle move.w #$100,-(sp) trap #1 addq.l #6,sp

Return Value	Fpipe() returns E_OK (0) if successful or a negative GEMDOS error code otherwise.

Caveats	No more than 999 pipes created with Fpipe() may be in use at once.

Comments	This function is normally used by shells who wish to redirect the input and output of their child processes. Prior to lauching a child process, the shell redirects its input and output (as necessary) to the read and write ends of the newly created pipe.

Fputchar()

LONG Fputchar( handle, lchar, mode )

WORD handle;

LONG lchar;

WORD mode;

	Fputchar() writes a character to the specified file.

Opcode	264 (0x108)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	handle specifies the handle of the file to write a character to. If the file specified by handle is a pseudo-terminal then all four bytes of lchar are written (it should be formatted as a character read from Bconin() ), otherwise only the low byte of lchar is transmitted. mode is only valid if handle refers to a terminal device. If mode is TTY_COOKED (0x0001) then control characters (which could cause SIGINT or SIGTSTP signals to be raised) passed through this function will be interpreted and acted upon. Setting mode to 0 will cause control characters to have no special effect.

Binding	move.w mode,-(sp) move.l lchar,-(sp) move.w handle,-(sp) move.w #$108,-(sp) trap #1 lea 10(sp),sp

Return Value	Fputchar() returns 4L if the character was output to a terminal, 1L if the character was output to a non-terminal, 0L if the character could not be written (possibly because of flow control), EIHNDL (-37) if the handle was invalid, or a negative BIOS error code if an error occurred during I/O.

See Also	Cconout(), Cauxout(), Crawio(), Cprnout(), Bconout(), Fgetchar(), Fwrite()

Fread()

LONG Fread( handle, length, buf )

WORD handle;

LONG length;

VOIDP buf;

	Fread() reads binary data from a specified file from the current file pointer.

Opcode	63 (0x3F)

Availability	All GEMDOS versions.

Parameters	handle is the GEMDOS file handle of the file to read from. length specifies the number of bytes of data to read. buf is a pointer to a buffer (at least length bytes long) where the read data will be stored.

Binding	pea buf move.l length,-(sp) move.w handle,-(sp) move.w #$3F,-(sp) trap #1 lea 12(sp),sp

Return Value	Fread() returns either a positive amount indicating the number of bytes actually read (this number may be smaller than length if an EOF is hit) or a negative GEMDOS error code.

Caveats	Fread() will crash the system if given a parameter of 0 for length on GEMDOS versions lower than 0.15.

See Also	Fwrite(), Fopen(), Fclose()

Freadlink()

LONG Freadlink( bufsiz, buf, name )

WORD bufsiz;

char *buf, *name;

	Freadlink() determines what file the specified symbolic link refers to.

Opcode	303 (0x12F)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	bufsiz specifies the length of buffer buf into which the original file pointed to by the symbolic link name is written.

Binding	pea name pea buf move.w bufsiz,-(sp) move.w #$12F,-(sp) trap #1 lea 12(sp),sp

Return Value	Freadlink() returns 0 if successful or a negative GEMDOS error code otherwise.

See Also	Fsymlink()

Frename()

LONG Frename( reserved, oldname, newname )

WORD reserved;

char *oldname,*newname;

	Frename() renames a standard GEMDOS file. It may also be used to move a file in the tree structure of a physical drive.

Opcode	86 (0x56)

Availability	All GEMDOS versions.

Parameters	reserved is not currently used and should be 0. oldname is the GEMDOS file specification of the file's current name/location. newname is the GEMDOS file specification of the new name/location of the file.

Binding	pea newname pea oldname move.w #0,-(sp) trap #1 move.w #$56,-(sp) lea 12(sp),sp

Return Value	Frename() returns E_OK (0) if the operation was successful or a negative GEMDOS error code if not.

Caveats	Prior to GEMDOS version 0.15, this command may not be used to rename folders. Also, do not attempt to rename a file that is currently open under any version of GEMDOS.

Fseek()

LONG Fseek( offset, handle, mode )

LONG offset;

WORD handle,mode;

	Fseek() moves the file position pointer within a GEMDOS file.

Opcode	66 (0x42)

Availability	All GEMDOS versions.

Parameters	handle specifies the GEMDOS file handle of the file pointer to modify. The meaning of offset varies with mode as follows:

	Name	mode	Meaning
	SEEK_SET	0	offset specifies the positive number of bytes from the beginning of the file.
	SEEK_CUR	1	offset specifies the negative or positive number of bytes from the current file position.
	SEEK_END	2	offset specifies the positive number of bytes from the end of the file.

Binding	move.w mode,-(sp) move.w handle,-(sp) move.l offset,-(sp) move.w #$42,-(sp) trap #1 lea 10(sp),sp

Return Value	Fseek() returns a positive value representing the new absolute location of the file pointer from the beginning of the file or a negative GEMDOS error code.

Fselect()

WORD Fselect( timeout, rfds, wfds, reserved )

WORD timeout;

LONG *rfds, *wfds;

LONG reserved;

	Fselect() enumerates file descriptors which are ready for reading and/or writing.

Opcode	285 (0x11D)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	timeout specifies the maximum amount of time (in milliseconds) to wait for at least one of the specified file descriptors to become unblocked. If timeout is 0 then the process will wait indefinitely. rfds and wfds each point to a LONG bitmap describing the read and write file descriptors to wait for. Setting bit #10 of the LONG pointed to by rfds, for example, will cause Fselect() to return when GEMDOS handle 10 is available for reading. As many read or write file descriptors can be specified per call as desired. Specifying NULL for either rfds or wfds is the same as passing a pointer to a LONG with no bits set.Upon return the LONGs pointed to by rfds and wfds will be filled in with a similar bitmap indicating which handles are ready to be read/written. reserved should always be set to 0L.

Binding	move.l reserved,-(sp) pea wfds pea rfds move.w timeout,-(sp) move.w #$11D,-(sp) trap #1 lea 16(sp),sp

Return Value	Fselect() returns the sum of bits set in both rfds and wfds. A return value of 0 indicates that the function timed out before any of the specified file handles became available. A negative GEMDOS error code is returned if the function failed.

Caveats	Fselect() does not currently work on any BIOS device except the keyboard.

Comments	Fselect( 0L, 0L, 0L, 0L) will block the calling process forever.

See Also	Finstat(), Foutstat()

Fsetdta()

VOID Fsetdta( ndta )

DTA *ndta;

	Fsetdta() sets the location of a new DTA (Disk Transfer Address) in memory.

Opcode	26 (0x1A)

Availability	All GEMDOS versions.

Parameters	ndta is a pointer to a valid memory area which will be used as the new DTA. The DTA structure is defined under the entry for Fgetdta().

Binding	pea ndta move.w #$1A,-(sp) trap #1 addq.l #6,sp

Comments	When an application starts, its DTA overlaps the command line string in the processes' basepage. Any use of the Fsfirst() or Fsnext() call without first reallocating a new DTA will cause the processes' command line to be corrupted.To prevent this, you should use Fsetdta() to define a new DTA structure for your process prior to using Fsfirst() or Fsnext(). Be careful to avoid assigning your DTA to a local or automatic variable without setting it to its original value before the variable goes out of scope.

See Also	Fgetdta(), Fsfirst(), Fsnext()

Fsfirst()

WORD Fsfirst( fspec, attribs )

char *fspec;

WORD attribs;

	Fsfirst() searches the file/pathspec given for the first occurrence of a file or subdirectory with named attributes and if found, fill in the current DTA with that file's information.

Opcode	78 (0x4E)

Availability	All GEMDOS versions.

Parameters	fspec is the GEMDOS file specification of the file or subdirectory to search for. This specification may use wildcard characters (? or ) within the filename, however they may not be used within the pathname. This function is the only GEMDOS* function which accepts wildcard characters in the path specification.attribs is a bit mask which can combine several file characteristics that further narrows the search as follows:

		Name	Bit Mask	Meaning
		FA_READONLY	0x01	Include files which are read-only.
		FA_HIDDEN	0x02	Include hidden files.
		FA_SYSTEM	0x04	Include system files.
		FA_VOLUME	0x08	Include volume labels.
		FA_DIR	0x10	Include subdirectories.
		FA_ARCHIVE	0x20	Include files with archive bit set.

Binding	move.w attribs,-(sp) pea fspec move.w #$4E,-(sp) trap #1 addq.l #8,sp

Return Value	Fsfirst() returns E_OK (0) if a file was found and the DTA was successfully filled in with the file information. Otherwise, it returns a negative GEMDOS error code.The DTA structure is defined as: typedef struct { BYTE d_reserved[21]; BYTE d_attrib; UWORD d_time; UWORD d_date; LONG d_length; char d_fname[14]; } DTA;

Comments	This function uses the application's DTA which is initially located in the same memory location as the processes' command line. Using this function without first assigning a new DTA will corrupt the command line.When running in the MiNT domain (see Pdomain()), Fsfirst() and Fsnext() will fill in the DTA with lowercase filenames rather than the standard TOS uppercase.

See Also	Fsnext(), Fgetdta(), Fsetdta()

Fsnext()

WORD Fsnext( VOID )

	Fsnext() should be called as many times as necessary after a corresponding Fsfirst() call to reveal all files which match the search criteria.

Opcode	79 (0x4F)

Availability	All GEMDOS versions.

Binding	move.w #$4F,-(sp) trap #1 addq.l #2,sp

Return Value	Fsnext() returns E_OK (0) if another file matching the search criteria given in Fsfirst() is found and the DTA has been properly filled in with the file's information. Otherwise, a negative GEMDOS error code is returned.

Comments	This function uses the application's DTA which is initially located in the same memory location as the processes' command line. Using this function without first assigning a new DTA will corrupt the command line.This call should only be used after Fsfirst() and the contents of the DTA should not be modifed between the calls.

See Also	Fsfirst()

Fsymlink()

LONG Fsymlink( oldname, newname )

char *oldname, *newname;

	Fsymlink() creates a symbolic link to a file.

Opcode	302 (0x12E)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	oldname points to the file specification of the file to create a link to. newname points to the file specification of the link to create.

Binding	pea newname pea oldname move.w #$12E,-(sp) trap #1 lea 10(sp),sp

Return Value	Fsymlink() returns 0 if successful or a negative GEMDOS error code otherwise.

Comments	Fsymlink(), unlike Flink(), creates symbolic links, which, unlike hard links, can be setup between physical devices and file systems.An Fdelete() call to a symbolic link will delete the link, not the file. A call to Fdelete() on the original file will cause future references to the created symbolic link to fail.

See Also	Flink(), Freadlink()

Fwrite()

LONG Fwrite( handle, count, buf )

WORD handle;

LONG count;

VOIDP buf;

	Fwrite() writes the contents of a buffer to the specified GEMDOS file.

Opcode	64 (0x40)

Availability	All GEMDOS versions.

Parameters	handle is the handle of the file to write to. count specifies the number of bytes to write. buf indicates the starting address of the data to write.

Binding	pea buf move.l count,-(sp) move.w handle,-(sp) move.w #$40,-(sp) trap #1 lea 12(sp),sp

Return Value	Fwrite() returns the positive number of bytes actually written or a negative GEMDOS error code if the operation failed.

Caveats	Prior to GEMDOS version 0.15, calling Fwrite() with a count parameter of 0 will hang the system.

See Also	Fread()

Fxattr()

LONG Fxattr( flag, name, xattr )

WORD flag;

char *name;

XATTR *xattr;

	Fxattr() returns extended information about the specified file.

Opcode	300 (0x12C)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	flag specifies whether attributes returned by this call on symbolic links should be those of the file to which the link points or the link itself. A value of FX_FILE (0) causes the attributes to be those of the actual file whereas a value of FX_LINK (1) returns the attributes of the link itself.name specifies the name of the file from which attributes are to be read and placed in the XATTR structure pointed to by xattr. XATTR is defined as follows: typedef struct { UWORD mode; LONG index; UWORD dev; UWORD reserved1; UWORD nlink; UWORD uid; UWORD gid; LONG size; LONG blksize; LONG nblocks; WORD mtime; WORD mdate; WORD atime; WORD adate; WORD ctime; WORD cdate; WORD attr; WORD reserved2; LONG reserved3; LONG reserved4; } XATTR;XATTR's members have the following meaning:

	XATTR Element	Meaning
	mode	Masking mode with 0xF000 reveals the file type as one of the following: S_IFCHR (0x2000) S_IFDIR (0x4000) S_IFREG (0x8000) S_IFIFO (0xA000) S_IMEM (0xC000) S_IFLNK (0xE000)The lower three nibbles of mode is a bit mask which specifies the legal file access mode(s) as defined in Fchmod().
	index	This member combined with the dev field are designed to provide a unique identifier for a file under file systems which allow multiple files with the same filename.
	dev	This value represents either a BIOS device number or an identifier created by the file system to represent a remote device.
	reserved1	This structure element is currently reserved for future implementations of MiNT.
	nlink	This value specifies the current number of hard links attached to the file. On a file system that does not support hard links and for most regular files, nlink is 1.
	uid	uid is the user ID of the owner of the file.
	gid	gid is the group ID of the owner of the file.
	size	size is the length of the file in bytes.
	blksize	blksize specifies the size of blocks (in bytes) in this file system.
	nblocks	nblocks is the actual number of blocks the file is using on the device. This number may include data storage elements other used to keep track of the file (aside from the actual data).
	mtime, mdate	Time and date of the last file modification in GEMDOS format.
	atime, adate	Time and date of the last file access in GEMDOS format.
	ctime, cdate	Time and date of the file's creation in GEMDOS format.
	attr	Standard file attributes (same as read by Fattrib() ).
	reserved2	This structure element is currently reserved for future implementations of MiNT.
	reserved3	This structure element is currently reserved for future implementations of MiNT.
	reserved4	This structure element is currently reserved for future implementations of MiNT.

Binding	pea xattr pea name move.w flag,-(sp) move.w #$12C,-(sp) trap #1 lea 12(sp),sp

Return Value	Fxattr() returns 0 if successful or a negative GEMDOS error code otherwise.

See Also	Fattrib()

Maddalt()

LONG Maddalt( start, size )

VOIDP start;

LONG size;

	Maddalt() informs GEMDOS of the existence of additional 'alternative' RAM that would not normally have been identified by the system.

Opcode	20 (0x14)

Availability	Available as of GEMDOS version 0.19 only.

Parameters	start indicates the starting address for the block of memory to be added to the GEMDOS free list. size indicates the length of this block in bytes.

Binding	move.l size,-(sp) pea start move.w #$14,-(sp) trap #1 lea 10(sp),sp

Return Value	Maddalt() returns E_OK (0) if the call succeeds or a negative GEMDOS error code otherwise.

Comments	This call should only be used to identify RAM not normally identified by the BIOS at startup (added through a VME-card or hardware modification). Once this RAM has been identified to the system it may not be removed and should only be allocated and used via the standard system calls. In addition, programs wishing to use this RAM must have their alternative RAM load bit set or use Mxalloc() to specifically request alternative RAM.See the discussion earlier in this chapter for more information about the types of available RAM.

See Also	Mxalloc()

Malloc()

VOIDP Malloc( amount )

LONG amount;

	Malloc() requests a block of memory for use by an application.

Opcode	72 (0x48)

Availability	All GEMDOS versions.

Parameters	amount specifies the amount of memory (in bytes) you wish to allocate. You may pass a value of -1L in which case the function will return the size of the largest free block of memory.

Binding	move.l amount,-(sp) move.w #$48,-(sp) trap #1 addq.l #6,sp

Return Value	Malloc() returns NULL if there is no block large enough to fill the request or a pointer to the block if the request was satisfied. The memory allocated will be chosen based on the status of the processes' load flags. To specify the memory requirements in more detail, use Mxalloc().

Caveats	Prior to GEMDOS version 0.15, Malloc( 0L ) will return a pointer to invalid memory as opposed to failing as it should.

Comments	Because GEMDOS can only allocate a limited amount of blocks per process (as few as 20 depending on the version of GEMDOS), applications should limit their usage of this call by allocating a few large blocks instead of many small blocks or use a 'C' memory manager (like malloc() ) if possible.

See Also	Mxalloc()

Mfree()

WORD Mfree( startadr )

VOIDP startadr;

	Mfree() releases a block of memory previously reserved with Malloc() or Mxalloc() back into the GEMDOS free list.

Opcode	73 (0x49)

Availability	All GEMDOS versions.

Parameters	startadr is the starting address of the block to be freed. This address must be the same as that returned by the corresponding Malloc() or Mxalloc() call.

Binding	pea startadr move.w #$49,-(sp) trap #1 addq. #6,sp

Return Value	Mfree() returns E_OK (0) if the block was freed successfully or a negative GEMDOS error code otherwise.

See Also	Malloc(), Mxalloc()

Mshrink()

WORD Mshrink( startadr, newsize )

VOIDP startadr;

LONG newsize;

	Mshrink() releases a portion of a block's memory to the GEMDOS free list.

Opcode	74 (0x4A)

Availability	All GEMDOS versions.

Parameters	startadr is the address of the block whose size you wish to decrease. newsize is the length you now desire for the block.

Binding	move.l newsize,-(sp) pea startadr clr.w -(sp) // Required/Reserved Value move.w #$4A,-(sp) trap #1 lea 12(sp),sp

Return Value	Mshrink() returns E_OK (0) if the operation was successful or a negative GEMDOS error code otherwise.

Caveats	This call should be used only to 'shrink' a memory block, not to enlarge it.

See Also	Malloc(), Mxalloc(), Mfree()

Mxalloc()

VOIDP Mxalloc( amount, mode )

LONG amount;

WORD mode;

	Mxalloc() allocates a block of memory according to specified preferences.

Opcode	68 (0x44)

Availability	Available from GEMDOS version 0.19.

Parameters	amount specifies the length (in bytes) of the block requested. As with Malloc(), specifying -1L for amount will return the size of the largest block of memory available. With modes 0 or 1, the size of the largest block of available RAM from the specified type of RAM is returned. Modes 2 and 3 return the size of the largest available block or whichever type of RAM had the largest block. mode is a WORD bit array which specifies the type of memory requested as follows:

	Bit	Meaning
	0-1	Bits 0-1 represent a possible value of 0-3 representing the type of RAM to allocate as follows: Name Value Meaning MX_STRAM 0 Allocate only ST-RAM MX_TTRAM 1 Allocate only TT-RAM MX_PREFSTRAM 2 Allocate either, preferring ST-RAM MX_PREFTTRAM 3 Allocate either, preferring TT-RAM
	2	Not used (should be set to 0).
	3	If set, refer to bits 4-7 for memory protection advice, otherwise default to protection specified in program header. This bit is only valid in the presence of MiNT.
	4-7	Bits 4-7 represent a possible value of 0-7 representing the memory protection mode to place on the allocated block of memory. Currently valid values are: Name Value Meaning MX_HEADER 0 Refer to Program Header MX_PRIVATE 1 Private MX_GLOBAL 2 Global MX_SUPERVISOR 3 Supervisor Mode Only Access MX_READABLE 4 Read Only AccessThese bits are only consulted if bit 3 is set and MiNT is present.
	8-15	Not used (should be set to 0).

Binding	move.w mode,-(sp) move.l amount,-(sp) move.w #$44,-(sp) trap #1 addq.l #8,sp

Return Value	Mxalloc() returns NULL if the request could not be granted or a valid pointer to the start of the block allocated otherwise.

Comments	Mxalloc() should be used instead of Malloc() whenever it is available.

See Also	Malloc(), Mfree()

Pause()

VOID Pause( VOID )

	Pause() suspends the process until a signal is received.

Opcode	289 (0x121)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$121,-(sp) trap #1 addq.l #2,sp

Comments	If the signal handler does a 'C' longjmp() to a different point in the process or if the handler's purpose is to exit the process, this call will never return.

See Also	Psigblock(), Psignal(), Psigsetmask()

Pdomain()

WORD Pdomain( domain )

WORD domain;

	Pdomain() determines/modifies the calling processes' execution domain.

Opcode	281 (0x119)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	domain contains the domain code of the new process domain. Currently the only valid values are DOMAIN_TOS (0) for the TOS compatibility domain and DOMAIN_MINT (1) for the MiNT domain. Passing a negative value for domain will not change domains but it will return the current domain.

Binding	move.w domain,-(sp) move.w #$119,-(sp) trap #1 addq.l #4,sp

Return Value	Pdomain() returns the domain in effect prior to the call.

Comments	Process domain affects system calls like Fread(), Fwrite(), Fsfirst(), and Fsnext(). Processes behave as expected when under the TOS domain.When processes run under the MiNT domain, however, the behavior of Fread() and Fwrite() calls when dealing with terminals can be modified by Fcntl(). Also, Fsfirst() and Fsnext() may not necessarily return the standard DOS 8 + 3 file name format. MiNT domain processes must understand filenames formatted for different file systems.

See Also	Fcntl()

Pexec()

LONG Pexec( mode, fname, cmdline, envstr )

WORD mode;

char *fname,*cmdline,*envstr;

	Pexec() has many functions designed to spawn child processes depending on the selected mode.

Opcode	75 (0x4B)

Availability	Pexec() modes 0, 3, 4, and 5, are available in all GEMDOS versions. Mode 6 is available as of GEMDOS version 0.15. Mode 6 is available as of GEMDOS version 0.19. Modes 100, 104, 106, and 200 are only available in the presence of MiNT.

Parameters	mode defines the function of Pexec() and the meaning of its parameters and return value as defined below. For modes which load a program, fname specifies the GEMDOS file specification of the file to load. cmdline is pointer to a string containg the command line which will be passed to the calling program. The first byte of the string should indicate the length of the command line (maximum of 125 bytes). The actual command line starts at byte 2. envstr is a pointer to an environment which is copied and assigned to the child process. If envstr is NULL, the child inherits a copy of the parent's environment.

	Name	mode	Meaning
	PE_LOADGO	0	'LOAD AND GO' - Load and execute named program file and return a WORD exit code when the child terminates.
	PE_LOAD	3	'LOAD, DON'T GO' - Load named program. If successful, the LONG return value is the starting address of the child processes' basepage. The parent owns the memory of the child's environment and basepage and must therefore free them when completed with the child.
	PE_GO	4	'JUST GO' - Execute process with basepage at specified address. With this mode, fname and envstr are NULL. The starting address of the basepage of the process to execute is given in the cmdline parameter.
	PE_BASEPAGE	5	'CREATE BASEPAGE' - This mode allocates the largest block of free memory and creates a basepage in the first 256 bytes of it. fname should be set to NULL. It is the responsibility of the parent to load or define the child's code, shrink the memory block as necessary, and initialize the basepage pointers to the TEXT, DATA, and BSS segments of the program.With MiNT, use of this mode in conjunction with mode PE_CGO can be used to emulate the Pvfork() call without blocking the parent.
	PE_GOTHENFREE	6	'JUST GO, THEN FREE' - This mode is identical to mode PE_GO except that memory ownership of the child's environment and basepage belong to the child rather than the parent so that when the child Pterm()'s, that memory is automatically freed.
	PE_CLOADGO	100	'LOAD, GO, DON'T WAIT' - This mode is identical to mode PE_LOADGO except that the parent process is returned to immediately while the child continues to execute. The positive process ID of the child is returned. Environment and basepage memory blocks are freed automatically when the child Pterm()'s
	PE_CGO	104	'JUST GO, DON'T WAIT' - This mode is similar to mode PE_GO except that the parent process is returned to immediately while the child continues to execute concurrently. The positive process ID of the child is returned. Memory ownership of the environment and basepage are shared by the parent and child (this sharing extends to all memory owned by the parent). fname may be used to supply a name for the child, otherwise, if NULL is used, the name of the parent will be used. cmdline should point to the process basepage. envstr should be NULL.
	PE_NOSHARE	106	'JUST GO, DON'T WAIT, NO SHARING' - This mode is exactly the same as mode PE_CGO except that the child process owns its own environment and basepage sharing no memory with the parent.
	PE_REPLACE	200	'REPLACE PROGRAM AND GO' - This mode works like mode PE_CLOADGO except that the parent process is terminated immediately and the child process completely replaces the parent in memory retaining the same process ID. fname, cmdline, and envstr, are all normally passed and valid.

Binding	pea envstr pea cmdline pea fname move.w mode,-(sp) move.w #$4B,-(sp) trap #1 lea 16(sp),sp

Return Value	The value returned by Pexec() is dependent on the mode value and is therefore explained above. All Pexec() modes return a LONG negative GEMDOS error code when the call fails. A WORD negative value indicates the child was successfully run but it terminated returning a negative error code. In all cases, a process returning after having been interrupted with ctrl-c returns 0x0000FFE0 (-32).

Comments	Command lines longer than 126 bytes may be passed to processes aware of the Atari Extended Command Line Specification (see discussion earlier in this chapter).

See Also	shel_write()

Pfork()

WORD Pfork( VOID )

	Pfork() creates a copy of the current process.

Opcode	283 (0x11B)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$11B,-(sp) trap #1 addq.l #2,sp

Return Value	Pfork() returns the new process ID in the parent and a 0 in the child.

Caveats	If the parent is in supervisor mode when this call is made, the child is started in user mode anyway.

Comments	After a Pfork() call, two instances of one process will exist in memory. Program execution in both processes continue at the same point in the TEXT segment following this call. The parent's DATA and BSS segments are physically copied so that any variables that change in the child will not affect the parent and vice versa.New processes started with this call should not call Mshrink() but are required to do any GEM initialization such as appl_init() and v_opnvwk() again (if GEM usage is needed). Both the parent and child use Pterm() or Pterm0() to terminate themselves.

See Also	Pexec(), Pvfork()

Pgetegid()

WORD Pgetegid( VOID )

	Pgetegid() returns the effective group ID of the process.

Opcode	313 (0x139)

Availability	Available when a 'MiNT' cookie with a version of at least 0.95 exists.

Binding	move.w #$139,-(sp) trap #1 addq.l #2,sp

Comments	The effective group ID of a process will be different than its actual group ID if its set gid bit is set. This mechanism allows users to grant file access to other users.

See Also	Pgetgid(), Pgeteuid()

Pgeteuid()

WORD Pgeteuid( VOID )

	Pgeteuid() returns the effective user ID of the process.

Opcode	312 (0x138)

Availability	Available when a 'MiNT' cookie with a version of at least 0.95 exists.

Binding	move.w #$138,-(sp) trap #1 addq.l #2,sp

Comments	The effective group ID of a process will be different than its actual group ID if its set gid bit is set. This mechanism allows users to grant file access to other users.

See Also	Pgetuid(), Pgetegid()

Pgetgid()

WORD Pgetgid( VOID )

	Pgetgid() returns the group ID (0-255) of the calling process.

Opcode	271 (0x10F)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$10F,-(sp) trap #1 addq.l #2,sp

See Also	Psetgid()

Pgetpgrp()

WORD Pgetpgrp( VOID )

	Pgetpgrp() returns the process group ID code for the calling process.

Opcode	269 (0x10D)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$10D,-(sp) trap #1 addq.l #2

Comments	Process groups are closely related processes which are used for job control and signaling purposes. Process groups usually terminate together rather than one at a time.

See Also	Psetpgrp(), Pkill()

Pgetpid()

WORD Pgetpid( VOID )

	Pgetpid() returns the positive WORD process ID code for the calling process. This identifer uniquely identifies the process within the system.

Opcode	267 (0x10B)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$10B,-(sp) trap #1 addq.l #2,sp

Pgetppid()

WORD Pgetppid( VOID )

	Pgetppid() returns the process ID for the calling processes' parent.

Opcode	268 (0x10C)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$10C,-(sp) trap #1 addq.l #2,sp

Return Value	Pgetppid() returns the process ID code for the parent of the calling process or 0 if it was started by the kernel (not a child process).

Pgetuid()

WORD Pgetuid( VOID )

	Pgetuid() returns the user ID code (0-255) of the calling process which determines access permissions and can be used in a multi-user system to differentiate users.

Opcode	271 (0x10F)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$10F,-(sp) trap #1 addq.l #2

See Also	Psetuid()

Pkill()

WORD Pkill( pid, sig )

WORD pid, sig;

	Pkill() sends a signal to one or more processes.

Opcode	273 (0x111)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	Pkill() sends signal sig to certain processes based on the value of pid. If pid is positive, the signal is sent the the process with process identifier pid. If pid is 0, the signal is sent to all processes who belong to the same process group as the caller as well as the caller itself. If pid is negative, the signal is sent to all processes with process group number -pid.

Binding	move.w sig,-(sp) move.w pid,-(sp) move.w #$111,-(sp) trap #1 addq.l #6,sp

Return Value	Pkill() returns 0 if successful or a negative GEMDOS error code otherwise.

Comments	If the caller is also a recipient of a signal and that signal causes program termination this call will never return.

See Also	Psignal()

Pmsg()

WORD Pmsg( mode, mboxid, msgptr )

WORD mode;

LONG mboxid;

PMSG *msgptr;

	Pmsg() sends/receives a message to/from a 'message box'.

Opcode	293 (0x125)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	mode specifies the action to take as follows:

	Name	mode	Operation
	MSG_READ	0	Block the process and don't return until a message is read from the specified mailbox ID mboxid and placed in the structure pointed to by msgptr.
	MSG_WRITE	1	Block the process and don't return until a process waiting for a message with mailbox ID mboxid has received the message contained in the structure pointed to by msgptr.
	MSG_READWRITE	2	Block the process until a process waiting for a message with mailbox ID mboxid has received the message contained in the structure pointed to by msgptr and a return message is received with mailbox ID 0xFFFFxxxx where 'xxxx' is the process ID of the current process.

	PMSG is defined as: typedef struct { LONG userlong1; LONG userlong2; WORD pid; } PMSG;On return from writes, pmsg.pid contains the process ID of the process who read your message, on return from reads, its the process ID of the writer. The contents of userlong1 and userlong2 is completely up to the sender.By OR'ing mode with MSG_NOWAIT (0x8000), you can prevent the call from blocking the process and simply return -1 if another process wasn't waiting to read or send your process a message.

Binding	pea msgptr move.l mboxid,-(sp) move.w mode,-(sp) move.w #$125,-(sp) trap #1 lea 12(sp),sp

Return Value	Pmsg() returns 0 if successful, -1 if bit 0x8000 is set and no process was ready to receive/send the desired message, or a negative GEMDOS error code.

Pnice()

WORD Pnice( delta )

WORD delta;

	Pnice() alters the process priority of the calling process.

Opcode	266 (0x10A)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	delta is a signed number which is added to the current process priority value. Positive values decrease process priority while negative values increase it.

Binding	move.w delta,-(sp) move.w #$10A,-(sp) trap #1 addq.l #4,sp

Return Value	Pnice() returns the prior process priority.

Comments	The process priority value has no fixed formula so it is hard to be able to predict the results of this call with any accuracy. This call is the same as Prenice( Pgetpid(), delta ).

See Also	Prenice()

Prenice()

LONG Prenice( pid, delta )

WORD pid, delta;

	Prenice() adjusts the process priority of the specified process.

Opcode	295 (0x127)

Availability	Available when a 'MiNT' cookie with a version of at least 0.90 exists.

Parameters	The process priority for the process with process ID pid is adjusted by signed value delta. Positive values for delta decrease process priority while negative values increase it.

Binding	move.w delta,-(sp) move.w pid,-(sp) move.w #$127,-(sp) trap #1 addq.l #6

Return Value	Prenice() returns a 32-bit negative GEMDOS error code if unsuccessful. Otherwise, the lower 16-bit signed value can be interpreted as the previous process priority code.

Comments	The exact effect adjusting process priorites will have is difficult to determine.

See Also	Pnice()

Prusage()

VOID Prusage( rusg )

LONG *rusg;

	Prusage() returns resource information about the current process.

Opcode	286 (0x11E)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	rusg is a pointer to an array of 8 LONGs as follows:

		Name	rusg[x]	Meaning
		PRU_KERNELTIME	0	Time spent by process in MiNT kernel.
		PRU_PROCESSTIME	1	Time spent by process in its own code.
		PRU_CHILDKERNALTIME	2	Total MiNT kernel time spent by children of this process.
		PRU_CHILDPROCESSTIME	3	Total user code time spent by children of this process.
		PRU_MEMORY	4	Total memory allocated by process (in bytes).
		-	5-7	Reserved for future use.

Binding	pea rusg move.w #$11E,-(sp) trap #1 addq.l #6,sp

Comments	All times given are in milliseconds.

See Also	Psetlimit()

Psemaphore()

LONG Psemaphore( mode, id, timeout )

WORD mode;

LONG id;

LONG timeout;

	Psemaphore() creates a semaphore which may only be accessed by one process at a time.

Opcode	308 (0x134)

Availability	Available when a 'MiNT' cookie with a version of at least 0.92 exists.

Parameters	mode specifies the mode of the operation which affects the other two parameters as follows:

	Name	mode	Meaning
	SEM_CREATE	0	Create a semaphore with called id and grant ownership to the calling process. timeout is ignored.
	SEM_DESTROY	1	Destroy the semaphore called id. This only succeeds if the semaphore is owned by the caller. timeout is ignored.
	SEM_LOCK	2	Request ownership of semaphore id. The process will wait for the semaphore to become available for timeout milliseconds and then return. If timeout value of 0 will force the call to return immediately whether or not the semaphore is available. A timeout value of -1 will cause the call to wait indefinitely.
	SEM_UNLOCK	3	Release ownership of semaphore id. The caller must be the current owner of the semaphore to release control. timeout is ignore.

Binding	move.l timeout,-(sp) move.l id,-(sp) move.w mode,-(sp) move.w #$134,-(sp) trap #1 lea 12(sp),sp

Return Value	Psemaphore() returns a 0 if successful, ERROR (-1) if the process requested a semaphore it already owned, or a negative GEMDOS error code.

Comments	If your process is waiting for ownership of a semaphore and it is destroyed by another process, an ERANGE (-64) error will result. Any semaphores owned by a process when it terminates are released but not deleted.

Psetgid()

WORD Psetgid( gid )

WORD gid;

	Psetgid() sets the group ID of the calling process.

Opcode	277 (0x115)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	gid is the group ID code to assign the calling process (0-255).

Binding	move.w gid,-(sp) move.w #$115,-(sp) trap #1 addq.l #4,sp

Return Value	Psetgid() returns gid if successful or EACCDN (-36) if the process did not have the authority to change the group ID.

Comments	The group ID of a process may only be changed when it is currently 0. Therefore, once the group ID has been set, it is fixed and unchangeable. Further attempts to modify it will result in an EACCDN error.

See Also	Pgetgid()

Psetlimit()

LONG Psetlimit( limit, value )

WORD limit;

LONG value;

	Psetlimit() reads/modifies resource allocation limits for the calling process and all of its children.

Opcode	287 (0x11F)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	limit defines the resource to read or modify as follows:

	Name	limit	Meaning
	LIM_MAXTIME	1	Maximum CPU time in milliseconds. If value is positive, value determines the new maximum. If value is 0, then the limit is set at 'unlimited'. If value is negative, the current value is returned but not modified.
	LIM_MAXMEM	2	Maximum total memory allowed for process. If value is positive, value determines the new maximum. If value is 0, then the limit is set at 'unlimited'. If value is negative, the current value is returned but not modified.
	LIM_MAXMALLOC	3	Maximum total size of each Malloc (Mxalloc). If value is positive, value determines the new maximum. If value is 0, then the limit is set at 'unlimited'. If value is negative, the current value is returned but not modified.

Binding	move.l value,-(sp) move.w limit,-(sp) move.w #$11F,-(sp) trap #1 addq.l #8,sp

Return Value	Psetlimit() returns the previous value or ERANGE (-64) if the value for limit was out of range.

Comments	The limits imposed by Psetlimit() are inherited from the parent by child processes.

See Also	Prusage()

Psetpgrp()

LONG Psetpgrp( pid, newgrp )

WORD pid, newgrp;

	Psetpgrp() sets the process group ID of the specified process.

Opcode	270 (0x10E)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	The process group ID of the process with process ID pid will have its process group ID changed to newgrp if the calling process has the same user ID or is the parent of the specified process. If pid is 0, the process group ID of the current process is sent. If newgrp is 0, the process group ID is set to equal the processes' (not the callers' unless pid is also set to 0) process ID.

Binding	move.w newgrp,-(sp) move.w pid,-(sp) move.w #$10E,-(sp) trap #1 addq.l #6,sp

Return Value	Psetpgrp() returns newgrp if successful or a negative GEMDOS error code otherwise.

See Also	Pgetpgrp()

Psetuid()

WORD Psetuid( uid )

WORD uid;

	Psetuid() sets the user ID of the calling process.

Opcode	272 (0x110)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	uid is the user ID to assign to the calling process.

Binding	move.w uid,-(sp) move.w #$110,-(sp) trap #1 addq.l #4,sp

Return Value	Psetuid() returns uid if successful or a negative GEMDOS error code otherwise.

Comments	As with the process group ID, the user ID of a process may only be set if it is currently 0. This means that once the user ID is set, it may not be changed.

See Also	Pgetuid()

Psigaction()

LONG Psigaction( sig, act, oact )

WORD sig;

SIGACTION *act, *oact;

	Psigaction() specifies a default action for the specified signal.

Opcode	311 (0x137)

Availability	Available when a 'MiNT' cookie with a version of at least 0.95 exists.

Parameters	sig specifies the signal whose action you wish to change. act points to a SIGACTION structure (as defined below) which defines the handling of future signals of type sig. oact points to a SIGACTION structure which defines the handling of pending signals of type sig. typedef struct { LONG sa_handler; WORD sa_mask; WORD sa_flags; } SIGACTION;Setting sa_hander to SIG_DFL (0) wll cause the default action to take place for the signal. A value of SIG_IGN (1) will cause the signal to be ignored. Any other value specifies the address of a signal handler.The signal handler should expect one LONG argument on its stack which contains the signal number being delivered. During execution of the handler, all signals specified in sa_mask are blocked.sa_flags is a signal-specific flag. When sig is SIGCHLD, setting Bit #0 (SA_NOCLDSTOP) will cause the SIGCHLD signal to be delivered only when the child process terminated (not when stopped).

Binding	move.w sig,-(sp) pea act pea oact move.w #$137,-(sp) trap #1 add.l #12,sp

Return Value	Psigaction() returns 0 if successful or a negative GEMDOS error code otherwise.

Comments	Calling Psigaction() automatically unmasks the specified signal for delivery.

See Also	Psignal

Psigblock()

LONG Psigblock( mask )

LONG mask;

	Psigblock() blocks selected signals from delivery.

Opcode	278 (0x116)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	mask is a bit mask of signals block. For each bit n set, signal n is added to the 'blocked' list.

Binding	move.l mask,-(sp) move.w #$116,-(sp) trap #1 addq.l #6,sp

Return Value	Psigblock() returns the original set of blocked signals in effect prior to the call.

Comments	Blocked signals are preserved with Pfork() and Pvfork() calls, however, children started with Pexec() start with an empty list of blocked signals.SIGKILL may not be blocked and will be reset by the system.

See Also	Pkill(), Psignal(), Psigpending()

Psignal()

LONG Psignal( sig, handler )

WORD sig;

VOID (*handler)( LONG );

	Psignal() determines the action taken when a signal is received by the process.

Opcode	274 (0x112)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	sig specifies the signal whose response you wish to modify. If handler is cast to SIG_DFL (0) then the default action for the signal will occur when received. If handler is cast to SIG_IGN (1) then the signal will be ignored by the process. Otherwise, handler points to a user function which is designed to take action on a signal. This function is called when a signal is received with a LONG signal number on the stack.

Binding	pea handler move.w sig,-(sp) move.w #$112,-(sp) trap #1 addq.l #8,sp

Return Value	Psignal() returns the old value of the signal handler if successful or a negative GEMDOS error code otherwise.

Comments	Signal handler functions may make any GEMDOS, BIOS, or XBIOS calls desired but must not make any AES or VDI calls. Signal handlers must either return with a 680x0 RTS instruction to resume program execution or call Psigreturn() to clean the stack if it intends to do a 'C' longjmp().Signal handling is preserved across Pfork() and Pvfork() calls. Child processes started with Pexec() ignore and follow the default action the same as their parents. Signals which have user functions assigned to them are reset to the default action for child processes.

See Also	Psigreturn(), Psigblock(), Pkill()

Psigpause()

LONG Psigpause( mask )

LONG mask;

	Psigpause() sets a new signal mask and then suspends the process until a signal is received.

Opcode	310 (0x136)

Availability	Available when a 'MiNT' cookie with a version of at least 0.95 exists.

Parameters	mask specifies the signal mask to wait for.

Binding	move.l mask,-(sp) move.w #$136,-(sp) trap #1 addq.l #6,sp

Return Value	Psigpause() returns 0 if successful or non-zero otherwise.

Comments	Depending on the state of the signal handler, this call may never return.

See Also	Psigaction(), Pause()

Psigpending()

LONG Psigpending( VOID )

	Psigpending() indicates which signals have been sent but not yet delivered to the calling process.

Opcode	291 (0x123)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #123,-(sp) trap #1 addq.l #2,sp

Return Value	Psigpending() returns a bit mask of which signals have been sent but not yet delivered to the calling process because they are being blocked. For each bit n set in the returned LONG, signal n is waiting for reception.

See Also	Psigblock(), Psignal(), Psigsetmask()

Psigreturn()

VOID Psigreturn( VOID )

	Psigreturn() prepares exit from a signal handler not planning to return via a 680x0 RTS.

Opcode	282 (0x11A)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$11A,-(sp) trap #1 addq.l #2,sp

Caveats	Calling this function and then calling the 680x0 RTS opcode to return will produce undesired results.

Comments	Psigreturn() is only needed by 'C' programs which intend to exit the signal handler by doing a 'C' longjmp() rather than simply using the 680x0 RTS.

See Also	Psignal()

Psigsetmask()

LONG Psigsetmask( mask )

LONG mask;

	Psigsetmask() defines which signals are to be blocked before being delivered to the calling application.

Opcode	279 (0x117)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	mask is a LONG bit mask which defines which signals to block and which signals to allow. For each bit n set, signal n will be blocked. For each bit n clear, signal n will be delivered.

Binding	move.l mask,-(sp) move.w #$117,-(sp) trap #1 addq.l #6,sp

Return Value	Psigsetmask() returns the original mask of blocked/unblocked signals prior to the call or a negative GEMDOS error code.

Comments	Unlike Psigblock(), mask completely replaces the old mask rather than simply OR'ing it.

See Also	Pkill(), Psignal(), Psigpending()

Pterm()

VOID Pterm( retcode )

WORD retcode;

	Pterm() terminates an application returning the specified error code.

Opcode	76 (0x4C)

Availability	All GEMDOS versions.

Parameters	retcode indicates the error status upon termination. Some recommended return values are:

	Name	retcode	Meaning
	TERM_OK	0	Program completion without errors
	TERM_ERROR	1	Generic Error
	TERM_BADPARAMS	2	Bad parameters
	TERM_CRASH	-1	Process crashed (returned by GEMDOS versions from 0.15.)
	TERM_CTRLC	-32	Process terminated by ctrl-c

Binding	move.w retcode,-(sp) move.w #$4C,-(sp) trap #1 addq.l #4,sp

Return Value	Pterm() never returns.

Comments	GEMDOS jumps through the etv_term (0x102) vector when this call is made prior to process termination to allow the process one last chance to clean up. In addition, all files opened by the process are closed and all memory blocks allocated by the process are freed.

See Also	Pexec(), Pterm0()

PtermØ()

VOID PtermØ( VOID )

	PtermØ() terminates the application returning an exit code of 0 indicating no errors.

Opcode	0 (0x00)

Availability	All GEMDOS versions.

Binding	clr.w -(sp) trap #1

Return Value	PtermØ() never returns.

Comments	Same as Pterm( 0 ).

See Also	Pterm()

Ptermres()

VOID Ptermres( keep, retcode )

LONG keep;

WORD retcode;

	Ptermres() terminates a process leaving a portion of the program's TPA intact and removing the memory left from GEMDOS's memory list.

Opcode	49 (0x31)

Availability	All GEMDOS versions.

Parameters	keep is the length (in bytes) of the processes' TPA to retain in memory after exit. retcode is the code returned on exit.

Binding	move.w retcode,-(sp) move.l keep,-(sp) move.w #$31,-(sp) trap #1 addq.l #8,sp

Return Value	Ptermres() never returns.

Comments	This function is normally used by TSR's to stay resident in memory. Any files opened by the process are closed. Any memory allocated is, however, retained. The value for keep is usually the sum of the length of the basepage (0x100), the length of the text, data, and bss segments of the application, and the length of the stack. It is important to note that the memory retained by this call may not be freed at a later point as it is removed from the GEMDOS memory list altogether.

See Also	Pterm0(), Pterm()

Pumask()

WORD Pumask( mode )

WORD mode;

	Pumask() defines an inital file and directory creation mask.

Opcode	307 (0x133)

Availability	Available when a 'MiNT' cookie with a version of at least 0.92 exists.

Parameters	mode specifies the new file access permission mask to apply to all future files created with Fcreate() and Dcreate(). mode is a WORD bit mask of various access permission flags as defined in Fchmod().

Binding	move.w mode,-(sp) move.w #$133,-(sp) trap #1 addq.l #4,sp

Return Value	Pumask() returns the original mask in effect prior to the call.

See Also	Dcreate(), Fcreate(), Fchmod()

Pusrval()

LONG Pursval( val )

LONG val;

	Pusrval() reads/modifies a user defined value associated with a process.

Opcode	280 (0x118)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	val specifies the new value of the LONG associated with this process. If val is -1 then this value is not changed but still returned.

Binding	move.1 val,-(sp) move.w #$118,-(sp) trap #1 addq.l #6,sp

Return Value	Pusrval() returns the original value of the user LONG prior to the call.

Comments	The user-defined longword set by this call is inherited by child processes and may be utilized as desired.

Pvfork()

WORD Pvfork( VOID )

	Pvfork() creates a duplicate of the current process which shares address and data space with the parent.

Opcode	275 (0x113)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$113,-(sp) trap #1 addq.l #2,sp

Return Value	Pvfork() returns the new process ID to the parent and 0 to the child. If an error occurs the parent receives a negative GEMDOS error code.

Caveats	If the parent is in supervisor mode when this call is made the child is placed in user mode anyway.

Comments	The child process spawned by this function shares all address and data space with the parent. In other words, any variables altered by the parent will also be altered by the child and vice versa. The child process should not call Mshrink() as its TPA is already correctly sized.The two processes do not execute concurrently. The parent is blocked until either the child terminates or calls Pexec()'s mode 200.

See Also	Pexec(), Pfork()

Pwait()

LONG Pwait( VOID )

	Pwait() attempts to determine the exit code of a stopped or terminated child process.

Opcode	265 (0x109)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$109,-(sp) trap #1 addq.l #2,sp

Return Value	Pwait() returns 0 if no child processes have terminated or a 32-bit return code for a child process which has been terminated or stopped.The process ID of the child process is placed in the upper 16 bits. A process which returned an exit status (via Pterm(), Ptermres(), or Pterm0() ) returns the exit code in the lower 16 bits.A process which was stopped as the result of a signal returns 0xnn7F where nn is the signal number which stopped it. A process which was terminated as the result of a signal returns 0xnn00 where nn is the signal number which killed the process.

Comments	Pwait() will block the calling process until at least one child has been stopped or terminated. Once the exit code of a process has been returned with this call it will be not be returned again with this call (unless it had been stopped and is restarted and stopped again). This call is identical to Pwait3( 2, NULL );

See Also	Pexec(), Pterm(), Ptermres(), Pterm0()

Pwait3()

LONG Pwait3( flag, rusage )

WORD flag;

LONG *rusage;

	Pwait3() determines the exit code of any children of the calling process which were stopped and/or terminated.

Opcode	284 (0x11C)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	flag is a bit mask which specifies the specifics of this call as follows:

	Name	Mask	Meaning
	PW_NOBLOCK	0x01	If set, the function will not block the calling process if no child has been stopped or terminated, rather it will simply return 0. If clear, the process will be blocked until a child of the process has terminated or is stopped.
	PW_STOPPED	0x02	If set, return exit codes for processes which have been terminated as well as stopped. If clear, only return exit codes for processes which have actually terminated.

	rusage points to an array of two LONGs which are filled in with resource usage information of the stopped or terminated process. The first LONG contains the number of milliseconds used by the child in user code. The second LONG indicates the number of milliseconds spent by the process in the kernel. rusage may be set to NULL if this information is undesired.

Binding	pea rusage move.w flag,-(sp) move.w #11C,-(sp) trap #1 addq.l #8,sp

Return Value	Pwait3() returns 0 if no child processes have been stopped and/or terminated (depending on flag) or a 32-bit return code for a child process which has been terminated or stopped.The process ID of the child process is placed in the upper 16 bits. A process which returned an exit status (via Pterm(), Ptermres(), or Pterm0() ) returns the exit code in the lower 16 bits.A process which was stopped as the result of a signal returns 0xnn7F where nn is the signal number which stopped it. A process which was terminated as the result of a signal returns 0xnn00 where nn is the signal number which killed the process.

See Also	Pwait(), Pexec(), Pterm(), Pterm0(), Ptermres(), Prusage()

Pwaitpid()

LONG Pwaitpid( pid, flag, rusage )

WORD pid, flag;

LONG *rusage;

	Pwaitpid() returns exit code information about one or more child processes.

Opcode	314 (0x13A)

Availability	Available when a 'MiNT' cookie with a version of at least 0.96 exists.

Parameters	pid specifies the children whose exit codes are of interest as follows.A pid of PWP_ALL (-1) indicates that all children are of interest. A pid of less than -1 indicates that any child whose process group is -pid is of interest. A pid of PWP_GROUP (0) indicates that any child with the same process group ID of the parent is of interest. A pid greater than 0 indicates that the child with the given process ID is of interest.For the usage of flag and rusage see Pwait3().

Binding	pea rusage move.w flag,-(sp) move.w pid,-(sp) trap #1 lea 10(sp),sp

Return Value	See Pwait3().

See Also	Pwait(), Pwait3()

Salert()

VOID Salert( str )

char *str;

	Salert() sends an alert string to the alert pipe 'U:\PIPE\ALERT\'.

Opcode	316 (0x13C)

Availability	Available when a 'MiNT' cookie with a version of at least 0.98 exists.

Parameters	str should point to a NULL terminated character string containing the alert message to display. The message should not contain any carriage returns or escape characters. The string should not be formatted as in form_alert().

Binding	pea str move.w #$13C,-(sp) trap #1 addq.l #6,sp

Caveats	Messages sent by Salert() are only delivered if a separate application is present which was designed to listen to the alert pipe and post its contents.

See Also	form_alert()

Super()

VOIDP Super( stack )

VOIDP stack;

	Super() allows you to interrogate or alter the state of the 680x0.

Opcode	32 (0x20)

Availability	All GEMDOS versions.

Parameters	stack defines the meaning of the call as follows:

	Name	stack	Meaning
	SUP_SET	(VOIDP)0	The processor is placed in supervisor mode and the old supervisor stack is returned.
	SUP_INQUIRE	(VOIDP)1	This interrogates the current mode of the processor. If the processor is in user mode a SUP_USER (0) is returned, otherwise a SUP_SUPER (1) is returned.
	-	>1	The processor is placed in user mode and the supervisor stack is reset to stack.

Binding	pea stack move.w #$20,-(sp) trap #1 addq.l #6,sp

Return Value	Super() returns a different value based on the stack parameter. The various return values are explained above.

Caveats	You should never call the AES in supervisor mode. In addition, supervisor mode should be entered and left in the same stack context (same 'C' function) or stack corruption can result.

Comments	To execute portion of a program in supervisor mode you normally call Super() with a parameter of 0 and save the return value. When ready to return to user mode you call Super() again with the saved return value as a parameter. Supervisor mode should be used sparingly under MiNT as no task switching can occur.

See Also	Supexec()

Sversion()

UWORD Sversion( VOID )

	Sversion() returns the current GEMDOS version number.

Opcode	48 (0x30)

Availability	All GEMDOS versions.

Binding	move.w #$30,-(sp) trap #1 addq.l #2,sp

Return Value	Sversion() returns a UWORD containing the GEMDOS minor version number in the upper word and the major version number in the lower word. Current values returned by Atari TOS's are:

	Return Value	TOS versions (normally) found in:
	0x1300 (0.13)	TOS 1.0, TOS 1.02
	0x1500 (0.15)	TOS 1.04, TOS 1.06
	0x1700 (0.17)	TOS 1.62
	0x1900 (0.19)	TOS 2.01, TOS 2.05, TOS 2.06, TOS 3.01, TOS 3.05, TOS 3.06
	0x3000 (0.30)	TOS 4.00, TOS 4.01, TOS 4.02, TOS 4.03, TOS 4.04, MultiTOS 1.00, MultiTOS 1.08

Comments	The GEMDOS number is not associated with the TOS or AES version number. You should check for GEMDOS or MiNT version numbers when trying to determine the presence or properties of a GEMDOS function.

Syield()

VOID Syield( VOID )

	Syield() surrenders the remainder of the callers' current process timeslice.

Opcode	255 (0xFF)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Binding	move.w #$FF,-(sp) trap #1 addq.l #2,sp

See Also	Pause(), Fselect()

Sysconf()

LONG Sysconf( inq )

WORD inq;

	Sysconf() returns information about the limits or capabilities of the currently running version of MiNT.

Opcode	290 (0x122)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	inq determines the return value as follows:

	Name	inq	Return Value
	SYS_MAXINQ	-1	Maximum legal value for inq.
	SYS_MAXREGIONS	0	Maximum memory regions per process.
	SYS_MAXCOMMAND	1	Maximum length of Pexec() command string.
	SYS_MAXFILES	2	Maximum number of open files per process.
	SYS_MAXGROUPS	3	Maximum number of supplementary group ID's.
	SYS_MAXPROCS	4	Maximum number of processes per user.

Binding	move.w inq,-(sp) move.w #$122,-(sp) trap #1 addq.l #4,sp

Return Value	See above.

Comments	If the requested item returns UNLIMITED (0x7FFFFFFF) then that item is unlimited.

See Also	Dpathconf()

Talarm()

LONG Talarm( time )

LONG time;

	Talarm() reads/sets a process alarm for the current process.

Opcode	288 (0x120)

Availability	This function is available under all MiNT versions integrated with MultiTOS.

Parameters	time specifies the length of time (in milliseconds) to wait before a SIGALRM signal is delivered. If time is 0 then any previously set alarm is cancelled. If time is negative the function does not modify any alarm currently set.

Binding	move.l time,-(sp) move.w #$120,-(sp) trap #1 addq.l #6,sp

Return Value	Talarm() returns 0 i f no alarm was scheduled prior to this call or the amount of time remaining (in milliseconds) before the alarm is triggered.

Caveats	An alarm with less than 1000 remaining milliseconds will return a value of 0.

Comments	If no SIGALRM signal handler has been set up when the alarm is triggered, the process will be killed.

See Also	Pause(), Psignal()

Tgetdate()

UWORD Tgetdate( VOID )

	Tgetdate() returns the current GEMDOS date.

Opcode	42 (0x2A)

Availability	All GEMDOS versions.

Binding	move.w #$2A,-(sp) trap #1 addq.l #2,sp

Return Value	Tgetdate() returns a bit array UWORD arranged as follows:

		Bits 15-9	Bits 8-5	Bits 4-0
		Years since 1980	Month (1-12)	Date (0-31)

See Also	Tgettime(), Tsetdate(), Gettime()

Tgettime()

UWORD Tgettime( VOID )

	Tgettime() returns the GEMDOS system time.

Opcode	44 (0x2C)

Availability	All GEMDOS versions.

Binding	move.w #$2C,-(sp) trap #1 addq.l #2,sp

Return Value	Tgettime() returns a bit array arranged as follows:

		Bits 15-11	Bits 10-5	Bits 4-0
		Hour (0-23)	Minute (0 to 59)	Secs/2 (0 to 29)

See Also	Tgetdate(), Tsettime(), Gettime()

Tsetdate()

WORD Tsetdate( date )

UWORD date;

	Tsetdate() sets the current GEMDOS date.

Opcode	43 (0x2B)

Availability	All GEMDOS versions.

Parameters	date is a bit array arranged as illustrated under Tgetdate().

Binding	move.w date,-(sp) move.w #$2B,-(sp) trap #1 addq.l #4,sp

Return Value	Tsetdate() returns 0 if the operation was successful or non-zero if a bad date is given.

Caveats	GEMDOS version 0.13 did not inform the BIOS of the date change and hence would not change the IKBD date or the date of a battery backed-up clock,

See Also	Tgetdate(), Tsettime(), Settime()

Tsettime()

WORD Tsettime( time )

UWORD time;

	Tsettime() sets the current GEMDOS time.

Opcode	45 (0x2D)

Availability	All GEMDOS versions.

Parameters	time is a bit array arranged as illustrated under Tgettime().

Binding	move.w time,-(sp) move.w #$2D,-(sp) trap #1 addq.l #4,sp

Return Value	Tsettime() returns 0 if the time was set or non-zero if the time given was invalid.

Caveats	GEMDOS version 0.13 did not inform the BIOS of the date change and hence would not change the IKBD date or the date of a battery backed-up clock.

See Also	Tgettime(), Tsetdate(), Settime()

Table of Contents | Index