GEMDOS
gemdos-trap
Date and Time
| • Fattrib | Reads or modifies file attributes. |
| • Fchdir | Sets the current directory from a file descriptor. |
| • Fchmod | Sets file access permissions. |
| • Fchown | Changes ownership of a filename to uid and gid respectively. |
| • Fchown16 | Changes ownership of a filename to uid and gid respectively. |
| • Fclose | Closes a given file. |
| • Fcntl | Performs control operations on a file. |
| • Fcreate | Creates a file. |
| • Fdatime | Reads or modifies a file's date/time stamp. |
| • Fdelete | Deletes a specified file. |
| • Fdirfd | Returns a file descriptor from a directory handle. |
| • Fdup | Duplicates file handle. |
| • Ffchmod | Changes access permissions for an open file. |
| • Ffchown | Changes ownership of an open file to uid and gid respectively. |
| • Ffdopendir | Opens a directory from a file descriptor. |
| • Fforce | Redirects input/output of standard channels. |
| • Ffstat64 | Obtains extended file attributes. |
| • Fgetchar | Reads characters from a file. |
| • Fgetdta | Gets disk transfer address. |
| • Finstat | Gets input status of a file. |
| • Flink | Creates a link to a file. |
| • Flock | Sets or removes file record lock. |
| • Fmidipipe | Redirects MIDI in/output. |
| • Fopen | Opens a specified file. |
| • Foutstat | Finds the output status of a file. |
| • Fpipe | Creates a pipe. |
| • Fpoll | Polls file descriptors. |
| • Fputchar | Writes a character to a specified file. |
| • Fread | Reads from a specified file. |
| • Freadlink | Finds the contents of a symbolic link. |
| • Frename | Renames a file. |
| • Fseek | Sets a pointer to a given position of a file. |
| • Fseek64 | Sets a pointer to a given 64-bit position of a file. |
| • Fselect | Selects file descriptors. |
| • Fsetdta | Modifies disk transfer address in memory. |
| • Fsfirst | Finds first entry in a directory. |
| • Fsnext | Finds next entry in a directory. |
| • Fsymlink | Creates symbolic link to a file. |
| • Fstat64 | Obtains extended file attributes. |
| • Fsync | Synchronize a file's in-core state with storage device. |
| • Fwrite | Writes to a file. |
| • Fxattr | Obtains extended file attributes. |
See also: Directory functions XBIOS drive functions Test for pipes
| Name: | »File attributes« - Read or modify file attributes.
| ||||||||
| Opcode: | 67
| ||||||||
| Syntax: | int16_t Fattrib ( const int8_t *filename, int16_t wflag,
int16_t attrib );
| ||||||||
| Description: | The GEMDOS routine Fattrib reads or sets the attributes of a
GEMDOS file.
Note: If possible, programs should make use of the Fxattr and Fchmod routines, as these are more efficient than Fattrib. | ||||||||
| Return value: | The function returns the following results:
| ||||||||
| Availability: | All GEMDOS versions.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fxattr
|
| C: | int16_t Fattrib ( const int8_t *filename, int16_t wflag,
int16_t attrib );
|
| Assembler: |
move.w attrib,-(sp) ; Offset 8 move.w wflag,-(sp) ; Offset 6 pea filename ; Offset 2 move.w #67,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; correct stack |
| GFA-Basic | Fehler%=Gemdos(&H43,L:filename%,W:wflag%,W:attrib%)
|
| Name: | »Set directory« - Set the current directory from a file
descriptor.
|
| Opcode: | 385
|
| Syntax: | int32_t Fchdir ( int16_t handle );
|
| Description: | The GEMDOS routine Fchdir sets the current directory for the
current process from a directory with the ID handle.
|
| Return value: | Returns E_OK on success or a negative GEMDOS error code
otherwise.
|
| Availability: | Available as of FreeMiNT version 1.17.
|
| Group: | File functions
|
| C: | int32_t Fchdir ( int16_t handle );
|
| Assembler: |
move.w handle,-(sp) ; Offset 2 move.w #385,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| GFA-Basic | Error%=Gemdos(&H181,W:handle%)
|
| Name: | »Fchmod« - Set permissions for file access.
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Opcode: | 306
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Syntax: | int32_t Fchmod ( int8_t *name, int16_t mode );
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Description: | The function alters the access rights for the GEMDOS file
name. The parameter mode contains the new access
rights:
For executable files the following applies:
Note: Not all file-systems need to support all the options. Unsupported access rights are then ignored. Execution rights for a directory mean that one may search in this directory for a name or name component. | ||||||||||||||||||||||||||||||||||||||||||||||||
| Return value: | The function can return the following results:
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists.
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||||||||||||||||||||||||||||||
| See also: | Binding Fattrib Fxattr XFS-concept in MagiC
|
| C: | int32_t Fchmod ( int8_t *name, int16_t mode );
|
| Assembler: |
move.w mode,-(sp) ; Offset 6 pea name ; Offset 2 move.w #306,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; correct stack |
| Name: | »Fchown« - Alter owner/group ID.
| ||||||
| Opcode: | 305
| ||||||
| Syntax: | int32_t Fchown ( int8_t *name, int16_t uid, int16_t gid );
| ||||||
| Description: | The function alters the user/group ID of the file name,
which control the access rights of the file.
This call can only be issued by a process that has an effective user identifier (EUID) which is 0, or which corresponds to the UID of the file; in the latter case the new UID must correspond to the old one, and in addition the calling process must be a member of the group with the group number GID. | ||||||
| Return value: | The function can return the following results:
| ||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists.
| ||||||
| Group: | File functions
| ||||||
| See also: | Binding Fchown16 Fchmod Fxattr XFS-concept in MagiC
|
| C: | int32_t Fchown ( int8_t *name, int16_t uid, int16_t gid );
|
| Assembler: |
move.w gid,-(sp) ; Offset 8 move.w uid,-(sp) ; Offset 6 pea name ; Offset 2 move.w #305,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| Name: | »Fchown16« - Alter owner/group ID.
| ||||||||
| Opcode: | 384
| ||||||||
| Syntax: | int32_t Fchown16 ( int8_t *name, int16_t uid, int16_t gid,
int16_t flag );
| ||||||||
| Description: | The function alters the user/group ID of the file name,
which control the access rights of the file.
The parameter flag specifies how symbolic links are to be treated. The following apply:
This call can only be issued by a process that has an effective user identifier (EUID) which is 0, or which corresponds to the UID of the file; in the latter case the new UID must correspond to the old one, and in addition the calling process must be a member of the group with the group number GID. | ||||||||
| Return value: | The function can return the following results:
| ||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least
1.16.0 exists.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fchown Fchmod Fxattr XFS-concept in MagiC
|
| C: | int32_t Fchown16 ( int8_t *name, int16_t uid, int16_t gid,
int16_t flag );
|
| Assembler: |
move.w flag,-(sp) ; Offset 10 move.w gid,-(sp) ; Offset 8 move.w uid,-(sp) ; Offset 6 pea name ; Offset 2 move.w #384,-(sp) ; Offset 0 trap #1 ; GEMDOS lea 12(sp),sp ; Correct stack |
| Name: | »File close« - Close a specified file.
| ||||
| Opcode: | 62
| ||||
| Syntax: | int16_t Fclose ( int16_t handle );
| ||||
| Description: | The GEMDOS routine Fclose closes a file with the file ID
handle.
Note: In a network the active locking is lifted. During closing of standard channels, from GEMDOS Version 0.15 onwards the original channel will be reinstated. | ||||
| Return value: | The function returns the following results:
| ||||
| Availability: | All GEMDOS versions.
| ||||
| Group: | File functions
| ||||
| See also: | Binding Fopen
|
| C: | int16_t Fclose ( int16_t handle );
|
| Assembler: |
move.w handle,-(sp) ; Offset 2 move.w #62,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H3E,W:handle%)
|
| Name: | »Fcntl« - Perform command operations on a given file.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Opcode: | 260
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Syntax: | int32_t Fcntl ( int16_t fh, int32_t arg, int16_t cmd );
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description: | The function performs various command operations on the file
with the handle fh. The parameter cmd describes the
desired operation, and can assume the following values. (arg
here depends on the selected command):
F_DUPFD (0): Duplicates the specified file handle. The following applies for the new interval: arg <= Handle < 32. If no free handles exist in the specified segment, the error-message ENHNDL will be returned. A call of Fdup (handle) is therefore equivalent to Fcntl (handle, 6L, F_DUPFD). F_GETFD (1): This command returns the non-inheritance flag for the handle fh. The flag is 0 when child processes started with Pexec are to inherit the file handle, otherwise it has the value 1 and the parameter arg is ignored. F_SETFD (2): This command sets the non-inheritance flag for the handle fh. arg specifies if child processes started with Pexec will inherit the file handle; a value of 1 indicates they will not, a value of 0 that they will. The default value for the flag is 0 for the standard GEMDOS handles in the region 0...5 and 1 for all others, i.e. non-standard handles. F_GETFL (3): This command returns the file descriptor flags that can be altered by the user. We are here dealing with the parameter mode specified at Fopen, as long as this has not been altered by another call of Fcntl. arg is ignored. F_SETFL (4): This command sets the file descriptor flags that can be altered by the user to arg (the other bits are ignored, and should be set to the value 0). It is not possible to alter the read/write mode or the modes for file sharing. F_GETLK (5): The parameter arg is a pointer to an flock structure, in which information about file locks are stored. If a lock exists then it will be copied into the structure. During this the element l_pid will hold the PID of the locking process. If no lock exists, then the element l_type will be set to the value F_UNLCK. For the case that the lock is held by another computer in a network, the element l_pid is set to a value defined by the NFS (Network File System). For this value, 0x1000 <= l_pid <= 0xffff. One should note that normal PID's have a value smaller than 1000. F_SETLK (6): This command sets (l_type = F_RDLCK or F_WRLCK) or lifts (l_type = F_UNLCK) an advisory lock on the specified file. If this is a FIFO queue (First-In-First-Out), the whole file must be processed at the same time. For the case when the lock conflicts with locks set by other processes, the value ELOCKED will be returned. If one tries to lift a non-existent lock, the value ENSLOCK will be returned. One should note that read-locks may overlap, but write-locks may not. If a locked file is closed, or the corresponding process terminates, then all set locks will be lifted automatically (i.e. reset). F_SETLKW (7): Similar to F_SETLK, with the difference that if the lock conflicts with those from other processes, then ELOCKED is not returned but the locked process is suspended until the locking from the other process is lifted. FSTAT (0x4600): Gets the extended attributes of a file. The parameter arg returns a pointer to an XATTR structure that is filled in with the file's extended attributes, as if an Fxattr call had been made. This command is supported in MagiC as of Version 3.0. FIONREAD (0x4601): In the parameter arg a pointer to a LONG value is returned which shows the number of bytes that may be read currently from a specified file handle without causing the process to block (wait for more input). The returned value is not necessarily correct, as the exact amount can only be estimated in some cases. The command is supported in MagiC as of Version 3.0. FIONWRITE (0x4602): Similar to FIONREAD, only here the number of bytes that may be written at present is returned. The command is supported in MagiC as of Version 3.0. FUTIME (0x4603): No information available at present. FTRUNCATE (0x4604): The parameter arg is a pointer to a LONG value that contains the new length of the file to be truncated. The command is supported in MagiC as of Version 3.0. FIOEXECPT (0x4605): In the parameter arg a pointer to a LONG value is returned which specifies whether the file is in an exception state (1) or not (0). The following commands are to be applied to all terminal devices such as the console or a pseudo-terminal: TIOCGETP (0x5400): This command returns via the parameter arg a pointer to a sgttyb structure, in which the parameters of the terminal are defined. TIOCSETN (0x5401): With this command one can set a new sgttyb structure which sets the parameters of the terminal. You should first get the terminal control parameters, modify what you wish to change, and then set them with this call. TIOCGETC (0x5402): This command returns via the parameter arg a pointer to a tchars structure in which the terminal control characters are defined. TIOCSETC (0x5403): With this command new terminal control characters can be set. For this one passes a pointer in arg to a tchars structure in which the control characters are defined. If a character is set to 0 then the corresponding function will be disabled. TIOCGLTC (0x5404): This command returns via the parameter arg a pointer to a ltchars structure in which extended terminal control characters are defined. TIOCSLTC (0x5405): With this command one can set new extended terminal control characters. To do this, one passes in arg a pointer to a ltchars structure in which the control characters are defined. If a character is set to 0 then the corresponding function will be disabled. TIOCGPGRP (0x5406): This command returns via the parameter arg a pointer to the process group ID of the terminal. TIOCSPGRP (0x5407): With this command one can set the process group ID of the terminal. To do this, one passes in the parameter arg a pointer to the corresponding process group. If processes from other groups should attempt to access this terminal (read or write) then they will be sent job control signals (SIGTSTP etc.). TIOCFLUSH (0x5408): With this command one can specify the type of flushing. For this, one passes a pointer in the parameter arg to a LONG value that describes the desired type. The following apply:
TIOCSTOP (0x5409): This command interrupts the output to the terminal (similar to flow control with Control-S). The parameter arg is ignored in this case. TIOCSTART (0x540a): This command restarts output to the terminal again (similar to flow control with Control-Q). The parameter arg is ignored in this case. TIOCGWINSZ (0x540b): With this command one can inquire the size of a text window. For this a pointer to a winsize structure is returned via the parameter arg. If an element of this structure has the value 0, then it means that the corresponding value is unknown. TIOCSWINSZ (0x540c): With this command one can set the window size. For this a pointer to a winsize structure is passed via the parameter arg which contains the required information. In this connection one should note that though the kernel handles the call, it leaves its execution to window managers. These also send the signal SIGWINCH if necessary. TIOCGXKEY (0x540d): This command returns the current definition of a system key (function, cursor etc.). For this a pointer to the xkey structure is passed in the parameter arg. The element xk_num of the structure has to be filled with the desired key:
The NULL-terminated string associated with the key (the convention of the C language applies) is returned via the element xk_def. TIOCSXKEY (0x540e): With this command one can set the current definition of a system key (function or cursor etc.). For this a pointer to the xkey structure is passed in the parameter arg, in which the elements xk_num and xk_def must have been set already. After the execution of the command, Fread returns the text string (instead of ASCII-0) specified in xk_def. This translation only happens, however, if the program has been set into the MiNT domain with Pdomain and if the terminal is reading characters using Fread. As the string passed in xk_def has to be NULL-terminated, one can pass a maximum of 7 characters in this way. TIOCIBAUD (0x5412): With this command one can set the Baud rate for input to the terminal. For this a pointer is passed via the parameter arg to a LONG value that specifies the Baud rate. TIOCOBAUD (0x5413): With this command one can set the Baud rate for output from the terminal. For this a pointer is passed via the parameter arg to a LONG value that specifies the Baud rate. TIOCCBRK (0x5414): This command clears bit 3 of the TSR register (the break condition) of the MFP68901 peripheral component. The parameter arg is ignored. TIOCSBRK (0x5415): This command sets bit 3 of the TSR register of the MFP68901 peripheral component. This causes a break signal to be sent as soon as the transmit register is empty. The parameter arg is ignored. TIOCGFLAGS (0x5416): This command returns in the lower 16 bits of the LONG pointed to by the parameter arg the terminal control flags (i.e. the current stop-bit and data-bit configuration). Valid mask values for arg are:
TIOCSFLAGS (0x5417): This command sets new terminal control flags that are passed via the parameter arg. TIOCOUTQ (0x5418): This command returns in arg a pointer to a LONG value in which the number of bytes in the output buffer is stored. TIOCSETP (0x5419): Functions in a similar way to TIOCSETN, but with the difference that (if the terminal supports TIOCOUTQ) the function only returns when the output buffer is empty. TCURSOFF (0x6300): This command switches off the cursor of the terminal. The parameter arg is ignored. TCURSON (0x6301): This command switches on the cursor of the terminal. The parameter arg is ignored. TCURSBLINK (0x6302): This command switches on blinking of the terminal's cursor. The blink rate can be set with TCURSSRATE. The parameter arg is ignored. TCURSSTEADY (0x6303): This command switches off blinking of the terminal's cursor again. The parameter arg is ignored. TCURSSRATE (0x6304): This command sets the blink rate of the terminal's cursor. For this a pointer to a WORD value is passed in arg which specifies after how many vertical blanks the cursor is to be inverted. TCURSGRATE (0x6305): This command obtains the cursor blink rate of the terminal. This is returned in a WORD value to which arg points. The following commands are applicable only for processes (opened as files). To open your own process as a file, you have to specify the path for Fopen as 'U:\PROC\processname.-1'. Here the extension -1 selects your own, and -2 the parent process. PBASEADDR (0x5002): In the parameter arg a pointer to the address of the GEMDOS basepage of the process opened as a file is returned. The command is supported in MagiC from Version 3.0 onwards. PPROCADDR (0x5001): In the parameter arg a pointer to the address of the PCB (Process Control Block) is returned. If memory protection is enabled, this memory cannot be read directly, use Fseek/Fread on the open process file. This is to prevent manipulation of process' rgid/ruid/egid/euid fields to e.g. become the root. PCTXTSIZE (0x5003): In the parameter arg a pointer to a LONG value is returned in which the length of the process context structure is specified. Two of these structures lie in memory before the PCB, whose address may be inquired with PPROCADDR. The first structure is responsible for the current process context, while the second contains the stored context of the last system call. PSETFLAGS (0x5004): This command sets the program flags (corresponding to those in the program header. For this a pointer to a LONG value is passed in arg whose lower 16 bits represent the program flags. PGETFLAGS (0x5005): This command obtains the current program flags. For this a pointer to these flags is returned via the parameter arg. PTRACESFLAGS (0x5006): This command sets the process trace flags. A pointer to a WORD value is passed in the parameter arg that represents the flags:
PTRACEGFLAGS (0x5007): This command obtains the current process trace flags. A pointer to these flags is returned via the parameter arg. PTRACEGO (0x5008): (from MC-68020 processor on) PTRACEFLOW (0x5009): PTRACESTEP (0x500a): PTRACE11 (0x500b): These functions should in future enable tracing of processes. The process to be traced must be in the 'suspended' state for this; it will be reawakened by the trace function. These functions are however not yet implemented at present. PLOADINFO (0x500c): arg is a pointer to the ploadinfo structure. fnamelen must contain the length of fname buffer in bytes and both cmdlin and fname must be preallocated (the former to at least 128 bytes and the latter to at least fnamelen bytes). Processes' command line will be copied into cmdlin. The complete path and filename of the process' parent will be copied into fname. If the buffer is too short the call will return EBADARG. PFSTAT (0x500d): This command corresponds to FSTAT. It obtains the extended attributes of the program file belonging to the process. The following commands are applicable only to files that represent shared memory: SHMGETBLK (0x4d00): This command returns the address of a memory block allocated with SHMSETBLK (or a NULL-pointer in case of error). For the sake of compatibility the parameter arg must be set to the value 0. Note: Different processes may see the memory block at different positions in their address space. For this reason a shared memory block may not contain absolute pointers to data! The command is supported in MagiC as of Version 3.0. SHMSETBLK (0x4d01): A pointer is passed in the parameter arg to a memory block that was earlier allocated with Malloc/Mxalloc. The memory is then offered for sharing under the filename of the file with the handle fh. For this the file must be created in the subdirectory U:\SHM. The block is marked in such a way that it will not be released at the termination of the process. The length will be obtained and used both for the opened file as well as entered in the directory. Invalid block addresses lead to the error-code EIMBA or to a bus- or address-error. The command is supported in MagiC as of Version 3.0. The following commands are of interest in connection with CD-ROM's: CDROMREADOFFSET (0x4300): This command obtains the block number of the first sector of the last session of a multi-session CD. The parameter arg contains this block number after the call. CDROMPAUSE (0x4301): This command causes a CD-ROM to enter the pause state when playing an audio CD. CDROMRESUME (0x4302): This command causes a CD-ROM to resume playing of an audio CD (pause is rescinded). CDROMPLAYMSF (0x4303): This command starts audio playback. The parameter arg is a pointer to a cdrom_msf structure, in which the start and end times are to be entered in MSF notation. CDROMPLAYTRKIND (0x4304): This command starts audio playback. The parameter arg is a pointer to a cdrom_ti structure in which the start and end positions are to be entered in track/index notation. In most audio CD's from the POP world the tracks are not subdivided any further. But many classical CD's also have finer markings within tracks as indices. Warning: Not every CD-ROM can access directly indices other than 1! CDROMREADTOCHDR (0x4305): This command allows one to obtain information about the structure of a CD. The parameter arg is a pointer to a cdrom_tochdr structure in which the first and last track of the CD are entered. CDROMREADTOCENTRY (0x4306): This command allows one to obtain further information about the structure of a CD. The parameter arg is a pointer to a cdrom_tocentry structure in which the desired information is entered. CDROMSTOP (0x4307): This command stops the corresponding drive. CDROMSTART (0x4308): This command starts the corresponding drive, and may also close the drawer. CDROMEJECT (0x4309): This command serves for opening the drawer of the corresponding drive. CDROMVOLCTRL (0x430a): This command permits altering the volume and channel assignments of the individual audio channels. The parameter arg is a pointer to a cdrom_volctrl structure. The command is compatible to the corresponding SunOS call. Warning: Altering the volume is not possible with all devices! CDROMSUBCHNL (0x430b): This command obtains the current position data, as well as the audio state. The parameter arg is a pointer to a cdrom_subchnl structure. CDROMREADMODE2 (0x430c): This command enables reading of Mode-2 sectors. Such sectors are used by XA-CDs (e.g.: Photo-CDs without error correction or Video-CDs) and contain 2336 bytes. The parameter arg is a pointer to a cdrom_read structure. Warning: Not all devices can read these sector types, and not all drivers offer this function. CDROMREADMODE1 (0x430d): This command enables reading of Mode-1 sectors. Such sectors have a size of 2048 bytes and are used on normal CD-ROMs. The parameter arg is a pointer to a cdrom_read structure. Warning: Not all devices can read these sector types, and not all drivers offer this function. CDROMPREVENTREMOVAL (0x430e): This command blocks the eject function of the corresponding CD-ROM. This can be useful, for instance, if the device is positioned in a public place and one wants to prevent theft of the CD. CDROMALLOWRMOVAL (0x430f): This command releases the eject function of the corresponding CD-ROM once more. CDROMAUDIOCTRL (0x4310): This command permits altering the volume and channel assignments of the individual audio channels. The parameter arg is a pointer to a cdrom_audioctrl structure. By setting the element set of this structure to the value 0, one can inquire the current settings. Warning: Altering the volume is not possible with all devices! CDROMREADDA (0x4311): This command permits the reading of Digital Audio (DA) sectors. Such sectors have a size of 2352 bytes, and contain per sector 588 samples in 16-bit stereo-PCM format. The parameter arg is a pointer to a cdrom_read structure. Warning: Not all devices can read these sector types, and not all drivers offer this function. CDROMGETMCN (0x4313): This command obtains the Media Catalog Number, which can be used theoretically to identify a CD easily. Unfortunately this information is present in only very few CDs. The parameter arg is a pointer to a cdrom_mcn structure. CDROMGETTISRC (0x4314): This command obtains the Track International Standard Recording Code, which should represent unique identifiers for individual tracks. The parameter arg is a pointer to a cdrom_tisrc structure. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return value: | The function can return the following results:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04, and
MagiC as of Version 3.0.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Group: | File functions.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See also: | Binding Fdup Flock Fopen Fxattr Pgetpgrp Psetpgrp
Metaioctl CD-ROM definitions
|
| C: | int32_t Fcntl ( int16_t fh, int32_t arg, int16_t cmd );
|
| Assembler: |
move.w cmd,-(sp) ; Offset 8 move.l arg,-(sp) ; Offset 4 move.w fh,-(sp) ; Offset 2 move.w #260,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| Name: | »File create« - Create a file.
| ||||||||||||||||||
| Opcode: | 60
| ||||||||||||||||||
| Syntax: | int16_t Fcreate ( const int8_t *fname, int16_t attr );
| ||||||||||||||||||
| Description: | The GEMDOS routine Fcreate creates a new file, or truncates an
existing one, with a given name and attributes. The following apply:
Note: In a network, the creation of a file sets the exclusivity. Whether the underlying GEMDOS is network capable can be established via the cookie _FLK. Note about MagiC: If bit 3 in attr is set, then the XFS function xfs_wlabel will be called. If this function can be executed without an error, then the value 0x0000fffc will be returned. This corresponds to a handle for the file NUL: or U:\DEV\NULL. However, this feature is only present for reasons of compatibility; as of MagiC 3, it is better to fall back on the function Dwritelabel. The specified attributes exist only under DOS file-systems and are ignored or emulated by other file-systems. With the Macintosh file-system (HFS), for instance, only bit 0 of attr is supported. Incidentally, symbolic links are dereferenced by this function, so that if the file already exists as a symbolic link, the file referenced from this link will be set to zero length. | ||||||||||||||||||
| Return value: | The function returns the following results:
| ||||||||||||||||||
| Availability: | All GEMDOS versions. However, GEMDOS Version 0.13 creating a
read-only file returns a handle that is of not much use. GEMDOS
versions below 0.15 wrongly allow more than one volume label per disk.
| ||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||
| See also: | Binding Fopen XFS-concept in MagiC
|
| C: | int16_t Fcreate ( const int8_t *fname, int16_t attr );
|
| Assembler: |
move.w attr,-(sp) ; Offset 6 pea fname ; Offset 2 move.w #60,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack |
| GFA-Basic | Handle%=Gemos(&H3c,L:fname%,W:attr)
|
| Name: | »File date and time« - Obtain or set creation date and time
of a file.
| ||||||||||||||
| Opcode: | 87
| ||||||||||||||
| Syntax: | void Fdatime ( DOSTIME *timeptr, int16_t handle, int16_t wflag
);
| ||||||||||||||
| Description: | The GEMDOS routine Fdatime reads or sets the date and time of
creation of a file. The following apply:
Note: Due to some errors in older versions of the GEMDOS, the function should be applied in the following way:
| ||||||||||||||
| Return value: | The function returns no direct result.
| ||||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||||
| Group: | File functions
| ||||||||||||||
| See also: | Binding Tgettime Tsettime
|
| C: | void Fdatime ( DOSTIME *timeptr, int16_t handle, int16_t wflag
);
|
| Assembler: |
move.w wflag,-(sp) ; Offset 8 move.w handle,-(sp) ; Offset 6 pea timeptr ; Offset 2 move.w #87,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H57,L:timeptr%,W:handle%,W:wflag%)
|
| Name: | »File delete« - Delete a file.
| ||||||
| Opcode: | 65
| ||||||
| Syntax: | int16_t Fdelete ( const int8_t *fname );
| ||||||
| Description: | The GEMDOS routine Fdelete deletes the file designated by
fname.
Note: The function should not be applied to opened files. As of MagiC 4, deletion also works for files with the 'Hidden' and 'System' attributes. In MagiC, furthermore, no symbolic links will be dereferenced, i.e. the link will be deleted and not the file or the folder to which the link points. | ||||||
| Return value: | The function returns the following results:
| ||||||
| Availability: | All GEMDOS versions.
| ||||||
| Group: | File functions
| ||||||
| See also: | Binding Fcreate
|
| C: | int16_t Fdelete ( const int8_t *fname );
|
| Assembler: |
pea fname ; Offset 2 move.w #65,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H41,L:fname%)
|
| Name: | »Fdirfd« - Return a file descriptor from a directory handle.
|
| Opcode: | 387 (0x0183)
|
| Syntax: | int16_t Fdirfd ( int32_t handle );
|
| Description: | The function Fdirfd returns a file descriptor from the
specified directory handle.
|
| Return value: | The function returns a file handle if successful, or a negative
error-message.
|
| Availability: | Available as of FreeMiNT version 1.17.
|
| Group: | File functions
|
| See also: | Binding Dopendir Dclosedir Dreaddir Drewinddir
Ffdopendir Pdomain
|
| C: | int16_t Fdirfd ( int32_t handle );
|
| Assembler: |
move.l handle,-(sp) ; Offset 2 move.w #387,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| Name: | »File duplicate« - Duplicate a file handle.
| ||||||||||||
| Opcode: | 69
| ||||||||||||
| Syntax: | int16_t Fdup ( int16_t handle );
| ||||||||||||
| Description: | The GEMDOS routine Fdup duplicates a standard file handle (0-5)
and assigns it a new handle (>6) for a standard channel. The
following apply:
Note: In all known GEMDOS versions (up to and including 0.19) errors occur if, after an Fdup, a program is started with Pexec. As of MagiC 4, one can also use this function to the device files -1, -2, -3 (system global) and -4 (NULL device). | ||||||||||||
| Return value: | The function returns the following results:
| ||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||
| Group: | File functions
| ||||||||||||
| See also: | Binding Fforce
|
| C: | int16_t Fdup ( int16_t handle );
|
| Assembler: |
move.w handle,-(sp) ; Offset 2 move.w #69,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| GFA-Basic | Phys_channel%=Gemdos(&H45,W:handle%)
|
| Name: | »Ffchmod« - Change access permissions for an open file.
|
| Opcode: | 258 (0x0102)
|
| Syntax: | int32_t Ffchmod ( int16_t fd, int16_t mode);
|
| Description: | See 'Name' above.
|
| Return value: | Returns E_OK on success or a negative GEMDOS error-code
otherwise.
|
| Availability: | Available as of FreeMiNT version 1.15.2
|
| Group: | File functions
|
| See also: | Binding Ffchown Fchmod
|
| C: | int32_t Ffchmod ( int16_t fd, int16_t mode);
|
| Assembler: |
move.w mode,-(sp) ; Offset 4 move.w fd,-(sp) ; Offset 2 move.w #258,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| Name: | »Ffchown« - Changes ownership of an open file to uid and gid
respectively.
|
| Opcode: | 257 (0x0101)
|
| Syntax: | int32_t Ffchown ( int16_t fd, int16_t uid, int16_t gid );
|
| Description: | This function changes ownership of an open file to uid
and gid respectively.
A non-privileged process can only change the ownership of a file that is owned by this user to the effective group id of the process or one of its supplementary groups. |
| Return value: | Returns E_OK on success or a negative GEMDOS error code
otherwise.
|
| Availability: | Available as of FreeMiNT version 1.15.2
|
| Group: | File functions
|
| See also: | Binding Ffchmod Fchown
|
| C: | int32_t Ffchown ( int16_t fd, int16_t uid, int16_t gid );
|
| Assembler: |
move.w gid,-(sp) ; Offset 6 move.w uid,-(sp) ; Offset 4 move.w fd,-(sp) ; Offset 2 move.w #257,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack |
| Name: | »Ffdopendir« - Duplicate a directory handle from a file
descriptor.
| ||||||
| Opcode: | 386 (0x0182)
| ||||||
| Syntax: | int32_t Ffdopendir ( int16_t fd );
| ||||||
| Description: | The function Ffdopendir duplicates a directory handle of a
opened directory by specifying its file descriptor. The flag
of the directory with ID fd is inherited by the new directory
handle.
| ||||||
| Return value: | The function returns a 32-bit directory handle if successful;
this may also be negative, but in no case may contain the value 0xff
in the higher byte, through which it can be differentiated from
errors.
In case of error, the following returns are possible:
| ||||||
| Availability: | Available as of FreeMiNT version 1.17.
| ||||||
| Group: | File functions
| ||||||
| See also: | Binding Dopendir Dclosedir Dreaddir Drewinddir Fdirfd
Pdomain
|
| C: | int32_t Ffdopendir ( int16_t fd );
|
| Assembler: |
move.w fd,-(sp) ; Offset 2 move.w #386,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| Name: | »File force« - Redirect standard file.
| ||||||||||||||||||||||
| Opcode: | 70
| ||||||||||||||||||||||
| Syntax: | int16_t Fforce ( int16_t stdh, int16_t nonstdh );
| ||||||||||||||||||||||
| Description: | The GEMDOS routine Fforce redirects a standard channel to a
specific other channel created by the application. The following
apply:
Under MiNT further channels may be redirected:
Note: As of MagiC 4, this function can be used to redirect device files -1,-2 and -3 (system global). The NULL device (-4) however may not be redirected. To redirect, say, screen output to a printer one can use a construct such as Fforce(1, Fdup(3)). | ||||||||||||||||||||||
| Return value: | The function returns the following results:
| ||||||||||||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||||
| Comment: | This function is used often to redirect the input or output of
a child process. It should be used together with Fdup to restore the
standard handle before the process terminates. You should note also
that any file handle redirected to a standard handle (say con:) will
be closed when the child exits and should not be closed by the parent.
| ||||||||||||||||||||||
| See also: | Binding Fdup Directory U:\DEV
|
| C: | int16_t Fforce ( int16_t stdh, int16_t nonstdh );
|
| Assembler: |
move.w nonstdh,-(sp) ; Offset 4 move.w stdh,-(sp) ; Offset 2 move.w #70,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H46,W:stdh%,W:nonstdh%)
|
| Name: | »Ffstat64« - Obtain extended file attributes of an open file.
| ||||||
| Opcode: | 349 (0x15d)
| ||||||
| Syntax: | int32_t Ffstat64 ( int16_t fd, STAT *stat );
| ||||||
| Description: | The function Ffstat64 obtains the extended attributes of an
open file, and saves these in stat.
Note: This function is equivalent to a call of Fcntl (mode F_STAT64). | ||||||
| Return value: | The function can return the following results:
| ||||||
| Availability: | This function is available as of FreeMiNT 1.16.
| ||||||
| Group: | File functions
| ||||||
| See also: | Binding Fattrib Fsnext Fstat64 STAT
|
| C: | int32_t Ffstat64 ( int16_t fd, STAT *stat );
|
| Assembler: |
pea stat ; Offset 4 move.w fd,-(sp) ; Offset 2 move.w #349,-(sp) ; Offset 0 trap #1 ; GEMDOS lea 8(sp),sp ; Correct stack |
| Name: | »Fgetchar« - Read a character from a file.
| ||||||||||
| Opcode: | 263
| ||||||||||
| Syntax: | int32_t Fgetchar ( int16_t fh, int16_t mode );
| ||||||||||
| Description: | The function reads a character from the file with the handle
fh. The parameter mode is only of interest when the
opened file is a (pseudo-)terminal. In that case the following values
apply:
The ASCII value of the character read will be stored in the low byte of the LONG returned by the function. For cases where the file is a (pseudo-)terminal, the scancode and Shift status will be returned as for Bconin. The individual modes of mode can naturally also be combined with an OR operation. Warning: This function is optional, hence a call may be answered with EINVFN. | ||||||||||
| Return value: | The function can return the following results:
| ||||||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Bconin Cconin Cauxin Fputchar Fread
|
| C: | int32_t Fgetchar ( int16_t fh, int16_t mode );
|
| Assembler: |
move.w mode,-(sp) ; Offset 4 move.w fh,-(sp) ; Offset 2 move.w #263,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| Name: | »Get disk transfer address« - Obtain the transfer address for
floppy disk operations.
|
| Opcode: | 47
|
| Syntax: | DTA *Fgetdta ( void );
|
| Description: | The GEMDOS routine Fgetdta obtains the address of a buffer for
Fsfirst and Fsnext.
|
| Return value: | The function returns a pointer to the address of the DTA
(Disk Transfer Address).
|
| Availability: | All GEMDOS versions.
|
| Group: | File functions
|
| Comment: | When an application launches, its DTA overlaps the command line
string in the process' basepage. Any use of the Fsfirst or Fsnext call
withoutn first reallocating a new DTA will cause the process' 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 of 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: | Binding Fsetdta Fsfirst Fsnext DTA
|
| C: | DTA *Fgetdta ( void );
|
| Assembler: |
move.w #47,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| GFA-Basic | Pointer%=Gemdos(&H2F)
|
| Name: | »Finstat« - Determine input status of a file.
| ||||
| Opcode: | 261
| ||||
| Syntax: | int32_t Finstat ( int16_t fh );
| ||||
| Description: | The function Finstat returns the maximum number of bytes that
may be read from a file with the handle fh without having to
wait.
If the number of bytes cannot be reported exactly, then the value 1 will be returned. Note: In MagiC, the kernel first tries to implement the call in Fcntl (FIONREAD). If this subfunction of dev_ioctl does not exist (i.e. the file driver returns EINVFN), then dev_stat will be called. In that case this can only result in the statement "Character available" (return == 1) or "No character available" (return == 0). FAT files and (1link [shared memory][Shared memory]) return the actual file length minus the current position. Pipes return the number of bytes present in the block. | ||||
| Return value: | The function can return the following results:
| ||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04, and
in MagiC as of Version 3.0.
| ||||
| Group: | File functions
| ||||
| See also: | Binding Cauxis Cconis Fcntl Foutstat
|
| C: | int32_t Finstat ( int16_t fh );
|
| Assembler: |
move.w fh,-(sp) ; Offset 2 move.w #261,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| Name: | »Flink« - Create a new (hard-)link to a file.
| ||||||||||
| Opcode: | 301
| ||||||||||
| Syntax: | int32_t Flink ( int8_t *oldname, int8_t *newname );
| ||||||||||
| Description: | The function Flink creates a new name (newname) for the
file named oldname. The file can later be addressed under both
names, and the deletion (with Fdelete) of one name has no effect on
the other.
One should note that oldname and newname have to lie on the same physical drive, and also that not all file-systems offer the option of setting links. | ||||||||||
| Return value: | The function can return the following results:
| ||||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists and in MagiC as of Version 3.0
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Frename Fsymlink XFS-concept in MagiC
|
| C: | int32_t Flink ( int8_t *oldname, int8_t *newname );
|
| Assembler: |
pea newname ; Offset 6 pea oldname ; Offset 2 move.w #301,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| Name: | »File record locking« - Lock or unlock part of a file.
| ||||||||||||||||
| Opcode: | 92
| ||||||||||||||||
| Syntax: | int32_t Flock ( int16_t handle, int16_t mode, int32_t start,
int32_t length );
| ||||||||||||||||
| Description: | The GEMDOS routine Flock serves to protect portions of a file
from access by other processes. The following apply:
Warning: This function is optional, hence the call may return EINVFN as a reply. In particular, one should note that Flock need not be available on all installed file-systems. | ||||||||||||||||
| Return value: | The function can return the following results:
| ||||||||||||||||
| Availability: | Only present when '_FLK' cookie exists.
| ||||||||||||||||
| Group: | File functions
| ||||||||||||||||
| See also: | Binding Fcreate Fopen Fclose Fdelete Ptermres
F_SETLK
|
| C: | int32_t Flock ( int16_t handle, int16_t mode, int32_t start,
int32_t length );
|
| Assembler: |
move.l length,-(sp) ; Offset 10 move.l start,-(sp) ; Offset 6 move.w mode,-(sp) ; Offset 4 move.w handle,-(sp) ; Offset 2 move.w #92,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $E(sp),sp ; Correct stack |
| Name: | »Fmidipipe« - Redirect MIDI input/output.
| ||||||||
| Opcode: | 294
| ||||||||
| Syntax: | int32_t Fmidipipe ( int16_t pid, int16_t in, int16_t out );
| ||||||||
| Description: | The function Fmidipipe alters the GEMDOS handles for MIDI inout
and output for the process with the ID pid. The parameters
in and out describe the GEMDOS handles that take on
MIDI input and output respectively for the process.
In the case pid = 0, the current process will be used. Then The function call is equivalent to the following two lines: Fforce (-4, in); Fforce (-5, out); | ||||||||
| Return value: | The function can return the following results:
| ||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fdup Fforce Test for pipes
|
| C: | int32_t Fmidipipe ( int16_t pid, int16_t in, int16_t out );
|
| Assembler: |
move.w out,-(sp) ; Offset 6 move.w in,-(sp) ; Offset 4 move.w pid,-(sp) ; Offset 2 move.w #294,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack |
| Name: | »File open« - Open a given file.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Opcode: | 61
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Syntax: | int32_t Fopen ( const int8_t *fname, int16_t mode );
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description: | The GEMDOS routine Fopen serves for opening specified files.
The following apply:
Warning: The file locking may be implemented in an advisory manner, i.e. it may be possible to access segments despite the presence of a lock. Programs that support file locking should therefore set their own lock before making an access and release it again immediately after the access. In this way one can guarantee that possible locks set by others will be respected. In MiNT and MagiC there are in addition the following modes available:
Note: For some devices, standard channel numbers already exist, so that it is not necessary to call Fopen. In detail:
According to Atari the standard channel numbers 4 and 5 are reserved, so that normal channel numbers for files only start at 6. In addition it is also possible to open the following character-oriented devices:
Symbolic links are automatically dereferenced by this function, i.e. if the file already exists as a symbolic link, the file referenced from it will be opened or, depending on the mode, truncated to zero length. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return value: | The function returns the corresponding file handle in the lower
WORD of the positive LONG, or a negative error-message.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See also: | Binding Fcreate The BIOS input/output channels F_SETLK
|
| C: | int32_t Fopen ( const int8_t *fname, int16_t mode );
|
| Assembler: |
move.w mode,-(sp) ; Offset 6 pea fname ; Offset 2 move.w #61,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack |
| GFA-Basic | Handle%=Gemdos(&H3D,L:fname%,W:mode%)
|
| Name: | »Foutstat« - Determine the output status of a file.
| ||||
| Opcode: | 262
| ||||
| Syntax: | int32_t Foutstat ( int16_t fh );
| ||||
| Description: | The function Foutstat returns the number of bytes that may be
written to the file with the handle fh without blocking the
corresponding process.
If the exact number of bytes cannot be specified, then the value 1 will be returned. Note: In MagiC, the kernel first tries to implement the call in Fcntl (FIONWRITE). If this subfunction of dev_ioctl does not exist (i.e. the file driver returns EINVFN), then dev_stat will be called. In that case this can only result in the statement "One character can be written" (return == 1) or "No character can be written" (return == 0). FAT files always return the value 1, shared memory returns the actual file length minus the current position. Pipes return the number of bytes still free in the block. | ||||
| Return value: | The function can return the following results:
Note that currently this function always returns 1 for disk files | ||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04, and
in MagiC as of Version 3.0.
| ||||
| Group: | File functions
| ||||
| See also: | Binding Cauxos Cconos Cprnos Fcntl Finstat
|
| C: | int32_t Foutstat ( int16_t fh );
|
| Assembler: |
move.w fh,-(sp) ; Offset 2 move.w #262,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| Name: | »Fpipe« - Create a pipe.
| ||||||||
| Opcode: | 256
| ||||||||
| Syntax: | int32_t Fpipe ( int16_t usrh[2] );
| ||||||||
| Description: | The function Fpipe creates a pipe that may be used for
inter-process communication (IPC). It is normally used by shells that
wish to redirect the input and output of their child processes; prior
to launching the child process, the shell redirects its input and
output (as necessary) to the read and write ends of the newly created
file. On a successful call, two GEMDOS handles will be returned in
usrh.
usrh[0] denotes the handle for the read-end of the pipe, (read-only) while usrh[1] the handle for the write-end of the pipe (write-only). The pipe produced in this way will be created in the directory U:\PIPE as a pseudo-file and will be named 'sys$pipe.xxx', where 'xxx' represent a three-digit integer. | ||||||||
| Return value: | The function can return the following results:
| ||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists and in MagiC as of Version 3.0.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fmidipipe Test for pipes
|
| C: | int32_t Fpipe ( int16_t usrh[2] );
|
| Assembler: |
pea usrh ; Offset 2 move.w #256,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| Name: | »Fpoll« - Enquiry of the file status with timeout.
| ||||||||||||||||||||||
| Opcode: | 346
| ||||||||||||||||||||||
| Syntax: | int32_t Fpoll (POLLFD *fds, uint32_t nfds, uint32_t timeout );
| ||||||||||||||||||||||
| Description: | Fpoll() performs a similar task to Fselect: it waits for one of
a set of file descriptors to become ready to perform I/O.
The set of file descriptors to be monitored is specified in the fds argument, which is an array of structures of the following form: typedef struct pollfd
{
int32_t fd; /* file descriptor */
uint16_t events; /* requested events */
uint16_t revents; /* returned events */
} POLLFD;
The caller should specify the number of items in the fds array in nfds. The field fd contains a file descriptor for an open file. If this field is negative, then the corresponding events field is ignored and the revents field returns zero. (This provides an easy way of ignoring a file descriptor for a single poll() call: simply negate the fd field.) The field events is an input parameter, a bit mask specifying the events the application is interested in for the file descriptor fd. If this field is specified as zero, then all events are ignored for fd and revents returns zero. The field revents is an output parameter, filled by the kernel with the events that actually occurred. The bits returned in revents can include any of those specified in events, or one of the values POLLERR, POLLHUP, or POLLNVAL. (These three bits are meaningless in the events field, and will be set in the revents field whenever the corresponding condition is true.) If none of the events requested (and no error) has occurred for any of the file descriptors, then poll() blocks until one of the events occurs. The timeout argument specifies the minimum number of milliseconds that poll() will block. (This interval will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.) Specifying a negative value in timeout means an infinite timeout. Specifying a timeout of zero causes poll() to return immediately, even if no file descriptors are ready. The bits that may be set/returned in events and revents are defined in <poll.h>:
When compiling with _XOPEN_SOURCE defined, one also has the following, which convey no further information beyond the bits listed above:
MiNT(Lib) also knows about, but does not use POLLMSG. | ||||||||||||||||||||||
| Return value: | The function can return the following results:
| ||||||||||||||||||||||
| Availability: | This function is available as of FreeMiNT 1.15.12.
| ||||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||||
| See also: | Binding Fselect Finstat Foutstat
|
| C: | int32_t Fpoll (POLLFD *fds, uint32_t nfds, uint32_t timeout );
|
| Assembler: |
move.l timeout,-(sp) ; Offset 10 move.l nfds,-(sp) ; Offset 6 pea fds ; Offset 2 move.w #346,-(sp) ; Offset 0 trap #1 ; GEMDOS lea 14(sp),sp ; Correct stack |
| Name: | »Fputchar« - Write a character to a given file.
| ||||||||||
| Opcode: | 264
| ||||||||||
| Syntax: | int32_t Fputchar ( int16_t fh, int32_t ch, int16_t mode );
| ||||||||||
| Description: | The function Fputchar writes a character to the file with the
handle fh. The parameter mode is only significant if
the file is a (pseudo-)terminal:
If the file is a (pseudo-)terminal, then all 4 bytes can be tranmitted. In this way it is possible to transmit simulated BIOS scancodes and Shift-status messages. Otherwise only the low byte of ch will be transmitted. | ||||||||||
| Return value: | The function can return the following values:
| ||||||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04.
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Bconout Cauxout Cconout Crawio Fgetchar
Fwrite
|
| C: | int32_t Fputchar ( int16_t fh, int32_t ch, int16_t mode );
|
| Assembler: |
move.w mode,-(sp) ; Offset 8 move.l ch,-(sp) ; Offset 4 move.w fh,-(sp) ; Offset 2 move.w #264,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| Name: | »file read« - Read from a file.
| ||||||||||
| Opcode: | 63
| ||||||||||
| Syntax: | int32_t Fread ( int16_t handle, int32_t count, void *buf );
| ||||||||||
| Description: | The GEMDOS routine Fread reads a given number of bytes from a
file. The following apply:
Note: In all GEMDOS Versions < 0.15 the system will freeze if the parameter count has a value of 0. When reading from standard channels, a maximum of 16383 characters may be read. | ||||||||||
| Return value: | The function returns either a positive number showing the
number of bytes actually read, which may be lower than count
if an EOF (end of file) was encountered, or a negative GEMDOS
error-code:
| ||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Fwrite FIONREAD
|
| C: | int32_t Fread ( int16_t handle, int32_t count, void *buf );
|
| Assembler: |
pea buf ; Offset 8 move.l count,-(sp) ; Offset 4 move.w handle,-(sp) ; Offset 2 move.w #63,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H3F,W:handle%,L:count%,L:buf%)
|
| Name: | »Freadlink« - Follow symbolic link.
| ||||||||||
| Opcode: | 303
| ||||||||||
| Syntax: | int32_t Freadlink ( int16_t bufsiz, int8_t *buf, int8_t *name
);
| ||||||||||
| Description: | The function Freadlink determines the filename of the symbolic
link name. This is the name that was specified for the first
parameter of Fsymlink.
The name is stored in buffer buf, which has a length of bufsiz characters. | ||||||||||
| Return value: | The function can return the following results:
| ||||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists and in MagiC as of Version 3.0.
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Fsymlink XFS-concept in MagiC
|
| C: | int32_t Freadlink ( int16_t bufsiz, int8_t *buf, int8_t *name
);
|
| Assembler: |
pea Name ; Offset 10 pea buf ; Offset 6 move.w bufsiz,-(sp) ; Offset 2 move.w #303,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack |
| Name: | »file rename« - Rename a GEMDOS file.
| ||||||||
| Opcode: | 86
| ||||||||
| Syntax: | int32_t Frename ( const int8_t *oldname, const int8_t *newname
);
| ||||||||
| Description: | The GEMDOS routine Frename serves for renaming files. The new
name may also contain a complete access path within the relevant
physical drive; in that case the file will be moved. The following
apply:
Note: As of GEMDOS Version 0.15 it is possible to alter the names of directories as well. However, these cannot be moved. One should avoid renaming files that are already open. Note about MagiC: It is up to the XFS to decide whether directories may be renamed or moved. The integrated DOS-XFS only allows a moving of directories as of MagiC 5. | ||||||||
| Return value: | The function returns the following results:
| ||||||||
| Availability: | All GEMDOS versions.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fdelete XFS-concept in MagiC
|
| C: | int32_t Frename ( const int8_t *oldname, const int8_t *newname
);
|
| Assembler: |
pea newname ; Offset 8 pea oldname ; Offset 4 move.w #0,-(sp) ; Offset 2 move.w #86,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack Note: The Null-parameter will normally be appended automatically for a C binding. |
| GFA-Basic | Fehler%=Gemdos(&H56,W:0,L:oldname%,L:newname%)
|
| Name: | »file seek« - Move file position pointer.
| ||||||||||||||||
| Opcode: | 66
| ||||||||||||||||
| Syntax: | int32_t Fseek ( int32_t offset, int16_t handle, int16_t
seekmode );
| ||||||||||||||||
| Description: | The GEMDOS routine Fseek permits the file pointer to be moved
to a new position within a file. The following apply:
Note: Applied to pipes the function returns the value EACCDN; this way applications can differentiate between devices and pipes. | ||||||||||||||||
| Return value: | The function returns a positive value of the new absolute
location of the file pointer from the start of the file, or a negative
error-message.
| ||||||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||||||
| Group: | File functions
| ||||||||||||||||
| See also: | Binding Fread Fwrite Test for pipes
|
| C: | int32_t Fseek ( int32_t offset, int16_t handle, int16_t
seekmode );
|
| Assembler: |
move.w seekmode,-(sp) ; Offset 8 move.w handle,-(sp) ; Offset 6 move.l offset,-(sp) ; Offset 2 move.w #66,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H42,L:offset%,W:handle%,W:seekmode%)
|
| Name: | »file seek« - Move 64-bit file position pointer.
| ||||||||||||||||||||
| Opcode: | 332 (0x014c)
| ||||||||||||||||||||
| Syntax: | int32_t Fseek64 ( int32_t hioffset, uint32_t lowoffset, int16_t
handle, int16_t seekmode, int64_t *newpos );
| ||||||||||||||||||||
| Description: | The GEMDOS routine Fseek64 permits the file pointer to be moved
to a new position within a file. The following apply:
Note: Applied to pipes the function returns the value EACCDN; this way applications can differentiate between devices and pipes. Note: At the moment Fseek64() is only a wrapper around Fseek() as there is no 64bit XFS/XDD support. If the specified offset is greater than 2147483647L (2^31-1), the call fails and returns EBADARG. | ||||||||||||||||||||
| Return value: | The function returns a positive value of the new absolute
location of the file pointer from the start of the file, or a negative
error-message.
| ||||||||||||||||||||
| Availability: | This function is available as of FreeMiNT 1.15.10.
| ||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||
| See also: | Binding Fread Fseek Fwrite Test for pipes
|
| C: | int32_t Fseek64 ( int32_t hioffset, uint32_t lowoffset, int16_t
handle, int16_t seekmode, int64_t *newpos );
|
| Assembler: |
pea newpos ; Offset 14 move.w seekmode,-(sp) ; Offset 12 move.w handle,-(sp) ; Offset 10 move.l lowoffset,-(sp) ; Offset 6 move.l hioffset,-(sp) ; Offset 2 move.w #332,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $12(sp),sp ; Correct stack |
| GFA-Basic |
Fehler%=Gemdos(&H14C,L:hioffset%,L:lowoffset%,W:handle%,W:seekmode%,L:newpos%)
|
| Name: | »Fselect« - Enquiry of the file status with timeout.
| ||||||
| Opcode: | 285
| ||||||
| Syntax: | int32_t Fselect ( uint16_t timeout, int32_t *rfds, int32_t
*wfds, ((int32_t) 0) );
| ||||||
| Description: | The function Fselect checks which open files are ready for
reading or writing. The parameter rfds points to a LONG bitmap
which describes the set of GEMDOS read file descriptors to wait for.
In this longword, bit n is set when the file descriptor n is to be checked for input. An empty set may also be represented optionally by a NULL-pointer. In the same way, wfds points to a set of write file descriptors whose output status is to be checked. On return of the function, the handles of the files that are ready for reading or writing respectively and also should be checked are passed in rfds and wfds. Note that currently the only BIOS device Fselect works with is the keyboard. With timeout one can specify how many milliseconds one should wait before the function returns. A value of 0 means in this case that the function waits until one of the specified files is ready for reading or writing. Example:
| ||||||
| Return value: | The function can return the following results:
| ||||||
| Availability: | As of the first in MultiTOS integrated MiNT version 1.04 and
MagiC since version 3.00.
| ||||||
| Group: | File functions
| ||||||
| See also: | Binding Finstat Foutstat
|
| C: | int32_t Fselect ( uint16_t timeout, int32_t *rfds, int32_t
*wfds, ((int32_t) 0) );
|
| Assembler: |
move.l dummy,-(sp) ; Offset 12 pea wfds ; Offset 8 pea rfds ; Offset 4 move.w timeout,-(sp) ; Offset 2 move.w #285,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $10(sp),sp ; Correct stack |
| Name: | »Set disk transfer address« - Set the address for the
transfer region for floppy disk operations.
|
| Opcode: | 26
|
| Syntax: | void Fsetdta ( DTA *buf );
|
| Description: | The GEMDOS routine Fsetdta sets the address of the memory
segment that will be used as the new DTA. The parameter buf is
a pointer to this structure.
Note: At program launch the DTA will be established starting at offset 0x80 in the basepage. |
| Return value: | The function does not return a result.
|
| Availability: | All GEMDOS versions.
|
| Group: | File functions
|
| See also: | Binding Fgetdta Fsfirst BASEPAGE DTA
|
| C: | void Fsetdta ( DTA *buf );
|
| Assembler: |
pea buf ; Offset 2 move.w #26,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H1A,L:buf%)
|
| Name: | »search first file« - Search for first file entry.
| ||||||||||||||||||||||||||
| Opcode: | 78
| ||||||||||||||||||||||||||
| Syntax: | int32_t Fsfirst ( const int8_t *filename, int16_t attr );
| ||||||||||||||||||||||||||
| Description: | The GEMDOS routine Fsfirst can obtain information about the
first occurrence of a file or subdirectory. The following apply:
The filename or path may also contain the jokers '*' and '?'. When the function terminates, the directory entry will fill the disk transfer area (DTA), whose location can be obtained or set with Fgetdta and Fsetdta respectively. The required information can then be obtained from the DTA structure. The DTA must be initialised with Fsfirst! Note: If the program runs in the MiNT-domain, Fsfirst will return lower case filenames. As file-systems exist that are case sensitive, you should avoid making such conversions manually. However, if you absolutely need upper case filenames you should use Pdomain to make your program run in the TOS-domain. Notes about MagiC: If bit 3 of attr is set, then the kernel will call the XFS function xfs_rlabel. The calling user program can unfortunately no longer get the date and time of the disk name under MagiC with this. The kernel sets all fields to 0 and the function Fsnext may not be executed. As of MagiC 3, the function Dreadlabel is used instead, which also manages long filenames. If bit 3 of attr is not set, a search for files is made as in TOS. If a file is a symbolic link, the DOS kernel calls the function Fxattr to follow the link. The values returned by Fxattr are then copied to the DTA. Warning: MagiC is not always able to evaluate correctly relative symbolic links during Fsfirst/Fsnext. There are three ways to overcome this:
Though MiNT handles this case correctly, it is at a huge cost. The Fsfirst/next concept is basically obsolete, ineffective and unsafe, and should be avoided both in MiNT as well as in MagiC. | ||||||||||||||||||||||||||
| Return value: | The function returns the following results:
| ||||||||||||||||||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||||||||||||||||||
| Group: | File functions
| ||||||||||||||||||||||||||
| See also: | Binding Fgetdta Fsetdta Fsnext DTA Recursive search XFS-concept
|
| C: | int32_t Fsfirst ( const int8_t *filename, int16_t attr );
|
| Assembler: |
move.w attr,-(sp) ; Offset 6 pea filename ; Offset 2 move.w #78,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H4E,L:filename%,W:attr%)
|
| Name: | »search next file« - Search for next file entry.
|
| Opcode: | 79
|
| Syntax: | int16_t Fsnext ( void );
|
| Description: | The GEMDOS routine Fsnext searches for the next file entry that
matches the criteria specified in Fsfirst. It should be called as
often as necessary after a Fsfirst call to find all files that match
the search criteria.
Be aware that this function uses the application's DTA which initially shares its memory location with the processes' command line. Hence using this function without first assigning a new DTA will corrupt the command line. Note: If the program runs in the MiNT-domain, Fsnext will return lower case filenames. As file-systems exist that are case sensitive, you should avoid making such conversions manually. However, if you absolutely need upper case filenames you should use Pdomain to make your program run in the TOS-domain. |
| Return value: | The function returns 0 if a matching file was found, else a
negative error-message.
|
| Availability: | All GEMDOS versions.
|
| Group: | File functions
|
| See also: | Binding Fgetdta Fsetdta Fsfirst
|
| C: | int16_t Fsnext ( void );
|
| Assembler: |
move.w #79,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #2,sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H4F)
|
| Name: | »Fsymlink« - Create a symbolic link to a file.
| ||||
| Opcode: | 302
| ||||
| Syntax: | int32_t Fsymlink ( int8_t *oldname, int8_t *newname );
| ||||
| Description: | The function Fsymlink creates a symbolic link newname
for the file named oldname. If the call succeeds then the file
can later be accessed under both names. Deletion with Fdelete for
newname does not affect the file itself, but only the symbolic
link. However, if Fdelete is applied to oldname, then the file
will be deleted as usual, and accesses to newname are no
longer possible.
The difference to hard links lies in the fact that symbolic links can exist between different physical devices (and with that even different file-system types). | ||||
| Return value: | The function can return the following results:
| ||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists and in MagiC as of Version 3.0.
| ||||
| Group: | File functions
| ||||
| See also: | Binding Flink Freadlink Frename XFS-concept
|
| C: | int32_t Fsymlink ( int8_t *oldname, int8_t *newname );
|
| Assembler: |
pea newname ; Offset 6 pea oldname ; Offset 2 move.w #302,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack |
| Name: | »Fstat64« - Obtain extended file attributes.
| ||||||||
| Opcode: | 331 (0x14b)
| ||||||||
| Syntax: | int32_t Fstat64 ( int16_t flag, int8_t *name, STAT *stat );
| ||||||||
| Description: | The function Fstat64 obtains the extended attributes of the
file whose complete name is specified in name, and saves these
in stat.
The parameter flag specifies how symbolic links are to be treated. The following apply:
Note: This function is equivalent to a call of Fcntl (mode F_STAT64) with the difference that instead of a filename, the handle of an already opened file is passed. | ||||||||
| Return value: | The function can return the following results:
| ||||||||
| Availability: | This function is available as of FreeMiNT 1.15.4.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fattrib Fsnext STAT
|
| C: | int32_t Fstat64 ( int16_t flag, int8_t *name, STAT *stat );
|
| Assembler: |
pea stat ; Offset 10 pea name ; Offset 6 move.w flag,-(sp) ; Offset 2 move.w #331,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack |
| Name: | »Fsync« - Synchronize a file's in-core state with storage
device.
| ||||||||
| Opcode: | 259 (0x0103)
| ||||||||
| Syntax: | int16_t Fsync ( int16_t handle );
| ||||||||
| Description: |
Fsync() transfers ("flushes") all modified in-core data of (i.e., modified buffer cache pages for) the file referred to by the file descriptor fd to the disk device (or other permanent storage device) so that all changed information can be retrieved even after the system crashed or was rebooted. This includes writing through or flushing a disk cache if present. The call blocks until the device reports that the transfer has completed. It also flushes metadata information associated with the file (see stat(2)). Calling Fsync() does not necessarily ensure that the entry in the directory containing the file has also reached disk. For that an explicit Fsync() on a file descriptor for the directory is also needed. Warning: In MiNT this function is currently not implemented and calls Sync() instead. | ||||||||
| Return value: | On success, these system call return zero. Otherwise, it
returns one of the following error codes:
| ||||||||
| Availability: | Available as of FreeMiNT version 1.15.10.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Sync
|
| C: | int16_t Fsync ( int16_t handle );
|
| Assembler: |
move.w handle,-(sp) ; Offset 2 move.w #259,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #4,sp ; Correct stack |
| Name: | »file write« - Write to a specified file.
| ||||||||||
| Opcode: | 64
| ||||||||||
| Syntax: | int32_t Fwrite ( int16_t handle, int32_t count, void *buf );
| ||||||||||
| Description: | The GEMDOS routine Fwrite writes a given number of bytes to a
specified GEMDOS file. The following apply:
Note about MagiC: If one passes the value 0 for the number of bytes to be written, and the value -1 in buf, then the file will be truncated to the current position of the file pointer. | ||||||||||
| Return value: | The function returns the number of bytes actually written, or
one of the following error-messages:
| ||||||||||
| Availability: | All GEMDOS versions.
| ||||||||||
| Group: | File functions
| ||||||||||
| See also: | Binding Fread FIONWRITE
|
| C: | int32_t Fwrite ( int16_t handle, int32_t count, void *buf );
|
| Assembler: |
pea buf ; Offset 8 move.l count,-(sp) ; Offset 4 move.w handle,-(sp) ; Offset 2 move.w #64,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack |
| GFA-Basic | Fehler%=Gemdos(&H40,W:handle,L:count%,L:buf%)
|
| Name: | »Fxattr« - Obtain extended file attributes.
| ||||||||
| Opcode: | 300
| ||||||||
| Syntax: | int32_t Fxattr ( int16_t flag, int8_t *name, XATTR *xattr );
| ||||||||
| Description: | The function Fxattr obtains the extended attributes of the file
whose complete name is specified in name, and saves these in
xattr.
The parameter flag specifies how symbolic links are to be treated. The following apply:
Note: This function is equivalent to a call of Fcntl (mode F_STAT) with the difference that instead of a filename, the handle of an already opened file is passed. | ||||||||
| Return value: | The function can return the following results:
| ||||||||
| Availability: | Available when a 'MiNT' cookie with a version of at least 0.90
exists and in MagiC as of Version 3.0.
| ||||||||
| Group: | File functions
| ||||||||
| See also: | Binding Fattrib Fsnext XFS-concept in MagiC
|
| C: | int32_t Fxattr ( int16_t flag, int8_t *name, XATTR *xattr );
|
| Assembler: |
pea xattr ; Offset 10 pea name ; Offset 6 move.w flag,-(sp) ; Offset 2 move.w #300,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack |
GEMDOS
gemdos-trap
Date and Time