HomeGEMDOSgemdos-trapDate and Time

5.9 File functions

Fattrib   Reads or modifies file atributes.
Fchmod    Sets file access permissions.
Fchown    Modifies file access permissions.
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.
Ffchmod   Changes access permissions for an open file.
Ffchown   Changes ownership of an open file to uid and gid respectively.
Fdup      Duplicates file handle.
Fforce    Redirects input/output of standard channels.
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.
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.
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.
Fwrite    Writes to a file.
Fxattr    Obtains extended file attributes.

See also: Directory functions   XBIOS drive functions   Test for pipes

5.9.1 Fattrib

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.
Parameter Meaning
   
filename Filename of the relevant file
wflag
0 = Read attributes
1 = Set attributes
attrib File attribute flags:
Bit 0: File is write-protected
Bit 1: File is hidden
Bit 2: System file
Bit 3: Volume label (diskette name)
Bit 4: Directory
Bit 5: Archive bit


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:
EACCDN : Access denied.
EFILNF : File not found.
EPTHNF : Directory not found.
Otherwise: The current file attributes.
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fxattr

5.9.1.1 Bindings for Fattrib

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%)

5.9.2 Fchmod

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:

Access by mode Meaning
Owner of the 0400 Read permission
file 0200 Write permission
  0100 Execution permission
     
Group of the 0040 Read permission
file 0020 Write permission
  0010 Execution permission
     
All other 0004 Read permission
users 0002 Write permission
  0001 Execution permission


For executable files the following applies:
mode Meaning
   
04000 Set effective UID of the process to the UID of whatever executes this process
02000 Set effective GID of the process to the GID of whatever executes this process
01000 The file is a directory.
Only the owner of the file or directory (or root) can delete files in this directory.
???? The file is a shared-text program.
The program is not removed from memory after it has been executed and therefore need not be reloaded for repeat use.


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:
E_OK   : No error has arisen
EFILNF : File not found
EPTHNF : Path to file not found
EACCDN : The EUID of the called process differs from the UID of the file owner and is also not that of the kernel (0)
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

5.9.2.1 Bindings for Fchmod

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

5.9.3 Fchown

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:
E_OK : No error has arisen
EINVFN : The file-system does not support the concept of user/group IDs (example TOS-FS)
EACCDN : The EUID of the calling process differs from the UID of the file-owner and is also non-zero
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists.
Group: File functions
See also: Binding   Fchmod   Fxattr   XFS-concept in MagiC

5.9.3.1 Bindings for Fchown

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

5.9.4 Fclose

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:
E_OK No error has arisen
EIHNDL Wrong file ID
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fopen

5.9.4.1 Bindings for Fclose

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%)

5.9.5 Fcntl

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:
Value Meaning
   
0 Flush input and output
Bit 0 set Flush input
Bit 1 set Flush output


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:

xk_num Key
0-9 F1-F10
10-19 F11-F20 (reached via Shift)
20 Cursor up
21 Cursor down
22 Cursor to right
23 Cursor to left
24 Help
25 Undo
26 Insert
27 Clr/Home
28 Shift + cursor up
29 Shift + cursor down
30 Shift + cursor to right
31 Shift + cursor to left


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:

Mask Meaning
0x0001 1 stop-bit
0x0002 1.5 stop-bits
0x0003 2 stop-bits
0x0000 8 data-bits
0x0004 7 data-bits
0x0008 6 data-bits
0x000C 5 data-bits


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.

PPROCADDDR (0x5001):
In the parameter arg a pointer to the address of the PCB (Process Control Block) is returned.

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:
P_ENABLE = 1 (Enable tracing)
P_DOS = 2 (Trace GEMDOS calls)
P_BIOS = 4 (Trace BIOS calls)
P_XBIOS = 8 (Trace XBIOS calls)


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):
This command returns in arg a pointer to the ploadinfo structure, in which the program name and command line are stored.

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:
>= 0 : No error occurred (deviations see above).
EIHNDL : Invalid file handle.
EINVFN : Command cannot be executed with the handle fh.
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

5.9.5.1 Bindings for Fcntl

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

5.9.6 Fcreate

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:
Parameter Meaning
   
fname Pointer to the filename.
attr File attributes:
Bit 0: File is write-protected
Bit 1: File is hidden
Bit 2: File is a system file
Bit 3: Volume label (diskette name)
Bit 5: Archive bit


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:
EPTHNF : Access path is incorrect.
ENHNDL : No more file handles left.
EACCDN : Write access denied.
Otherwise : ID of the file.
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

5.9.6.1 Bindings for Fcreate

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)

5.9.7 Fdatime

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:
Parameter Meaning
   
timeptr Pointer to date/time structure
handle File ID
wflag
0 = Obtain values
1 = Set values


Note: Due to some errors in older versions of the GEMDOS, the function should be applied in the following way:
  • Open file
  • Call Fdatime
  • Close file
Return value: The function returns no direct result.
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Tgettime   Tsettime

5.9.7.1 Bindings for Fdatime

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%)

5.9.8 Fdelete

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:
E_OK No error has arisen
EFILNF File not found
EACCDN Access denied
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fcreate

5.9.8.1 Bindings for Fdelete

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%)

5.9.9 Fdup

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:
handle Meaning
   
0 Keyboard (stdin:)
1 Screen (stdout:)
2 Serial port (stdaux:)
3 Parallel port (stdprn:)


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:
ENHNDL : No more handles available.
EIHNDL : Incorrect file handle.
Otherwise : The desired new handle.
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fforce

5.9.9.1 Bindings for Fdup

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%)

5.9.10 Ffchmod

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

5.9.10.1 Bindings for Ffchmod

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

5.9.11 Ffchown

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

5.9.11.1 Bindings for Ffchown

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

5.9.12 Fforce

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:
stdh Channel to be redirected
0 = Keyboard (stdin, con:)
1 = Screen (stdout, con:)
2 = Serial port (stdaux:)
3 = Parallel port (stdprn:)
nonstdh Number of the replacement channel (as above)


Under MiNT further channels may be redirected:
-1 = Refers to BIOS handle 2, redirects BIOS output
-2 = Refers to BIOS handle 1, redirects BIOS output
-3 = Refers to BIOS handle 0, redirects BIOS output
-4 = GEMDOS handles -4 and -5 refer
-5 = to MIDI input and output respectively. Redirecting them will affect BIOS handle 3.


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:
E_OK : No error has arisen
EIHNDL : Incorrect handle
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

5.9.12.1 Bindings for Fforce

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%)

5.9.13 Fgetchar

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:
mode Meaning
   
0 Raw mode
No evaluation of control characters
1 Cooked mode
Special control characters (Control-C, Control-Z) will be looked for and interpreted if appropriate; the same applies for flow control (Control-S, Control-Q)
2 Echo mode
Read characters will be output on the terminal


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:
>= 0 : No error, but the read character
0xff1a : End-of-File (EOF) was recognized
EIHNDL : Invalid file handle
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
Group: File functions
See also: Binding   Bconin   Cconin   Cauxin   Fputchar   Fread

5.9.13.1 Bindings for Fgetchar

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

5.9.14 Fgetdta

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

5.9.14.1 Bindings for Fgetdta

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)

5.9.15 Finstat

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:
>= 0 : No error occurred (number of bytes)
EIHNDL : Invalid file handle
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

5.9.15.1 Bindings for Finstat

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

5.9.16 Flink

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:
E_OK : No error has arisen
EINVFN : The file-system does not support hard links
EFILNF : The file oldname does not exist
EXDEV : (As below)
ENSAME : The files oldname/newname do not lie on the same physical drive
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

5.9.16.1 Bindings for Flink

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

5.9.17 Flock

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:
Parameter Meaning
   
handle File ID
mode
0 = Apply lock
1 = Remove lock
start Start position in the file
length Number of bytes affected


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:
E_OK : No error has arisen
ELOCKED : Overlapping portion of file already locked
ENSLOCK : Matching lock not found for removal
Availability: Only present when '_FLK' cookie exists.
Group: File functions
See also: Binding   Fcreate   Fopen   Fclose   Fdelete   Ptermres   F_SETLK

5.9.17.1 Bindings for Flock

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

5.9.18 Fmidipipe

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:
E_OK : No error has arisen
EFILNF : The process pid was not found
EACCDN : in/out are not open for reading or writing
EIHNDL : in/out is not a valid handle
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

5.9.18.1 Bindings for Fmidipipe

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

5.9.19 Fopen

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:
Parameter Meaning
   
fname Name of file to be opened
mode Mode, as bit-vector:
Bit-0..2 = Access mode
0 = Read only
1 = Write only
2 = Read and write
Bit-3 = Reserved (to be set to 0)
Bit-4..6 = Sharing-Modus
Bit-7 = Inheritance flag

The bits 3..7 are only available with a GEMDOS that offers file locking extensions (test for _FLK cookie). The inheritance flag determines whether a child started by a process inherits any open file handles and has the same access as the parent. If this flag is set then a child has to reopen any files it wishes to use and must face the same sharing restrictions that other processes must share. The sharing mode determines the way other processes may access the file once it has been opened. The following apply:
Sharing Meaning
   
0 Compatibility mode (will be used by those programs that do not know about network extensions). If the file's read-only bit is set then this is the same as deny writing; otherwise it is the same as deny reading/writing.
1 Reading and writing denied (the file may not be opened a second time)
2 Writing denied (the file may only be reopened for reading)
3 Reading denied (the file may only be reopened for writing)
4 Everything is allowed


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:
mode Meaning
   
0x080 Reserved for MiNT
0x100 Do not block file for I/O
0x200 Create file, if this does not exist
0x400 Set existing file to zero length
0x800 Do not open existing file


Note: For some devices, standard channel numbers already exist, so that it is not necessary to call Fopen. In detail:
Channel Meaning
   
0 Keyboard (stdin:)
1 Screen (stdout:)
2 Serial port (stdaux:)
3 Parallel port (stdprn:)


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:
  • PRN: (parallel port, -3)
  • AUX: (serial port, -2)
  • CON: (console, -1)


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

5.9.19.1 Bindings for Fopen

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%)

5.9.20 Foutstat

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:
>= 0 : No error arisen (number of bytes)
EIHNDL : Invalid file handle.


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

5.9.20.1 Bindings for Foutstat

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

5.9.21 Fpipe

Name: »Fpipe« - Create a pipe.
Opcode: 256
Syntax: int16_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:
E_OK : No error has arisen
ENHNDL : No 2 handles free any more
EACCDN : No pipeline free any more (max. 999 available)
ENSMEM : Not enough memory free to create the pipe
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

5.9.21.1 Bindings for Fpipe

C: int16_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

5.9.22 Fputchar

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:
mode Meaning
   
0 Raw mode
No evaluation of control characters
1 Cooked mode
Special control characters (Control-C, Control-Z) will be looked for and interpreted if appropriate; the same applies for flow control (Control-S, Control-Q)


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:
4 : Number of written bytes, if the file is a terminal
1 : Output successful, but file is not a terminal
0 : Bytes could not be written (perhaps due to flow control)
EIHNDL : Invalid file handle
  A negative BIOS error-code if an error occurred during I/O.
Availability: As of the first in MultiTOS integrated MiNT version 1.04.
Group: File functions
See also: Binding   Bconout   Cauxout   Cconout   Crawio   Fgetchar   Fwrite

5.9.22.1 Bindings for Fputchar

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

5.9.23 Fread

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:
Parameter Meaning
   
handle File handle identifier
count Number of bytes of data to read
buf Address of the receiving buffer (at least count bytes long)


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:
EIHNDL : Wrong file handle
ELOCKED : File segment is marked as locked
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fwrite   FIONREAD

5.9.23.1 Bindings for Fread

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%)

5.9.24 Freadlink

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:
E_OK : No error has arisen
EINVFN : The file-system of name does not permit any symbolic links
EFILNF : The symbolic link name was not found
EACCDN : name is not a symbolic link
ERANGE : The buffer buf is too small for the filename that is to be determined
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

5.9.24.1 Bindings for Freadlink

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

5.9.25 Frename

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:
Parameter Meaning
   
oldname Pointer to present name
newname Pointer to new name


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:
E_OK : No error has arisen
EPTHNF : Directory not found
EACCDN : Access denied (write-protected)
ENSAME : Destination not on same drive
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fdelete   XFS-concept in MagiC

5.9.25.1 Bindings for Frename

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%)

5.9.26 Fseek

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:
Parameter Meaning
   
offset Number of bytes that are to be skipped
handle GEMDOS file handle
seekmode Type of repositioning:
0 = From start of file
1 = From current position
2 = From end of file


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

5.9.26.1 Bindings for Fseek

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%)

5.9.27 Fselect

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:
Fselect (0, 0L, 0L, 0L) waits forever
Fselect (1, 0L, 0L, 0L) waits for one millisecond
Return value: The function can return the following results:
0 : In the specified time no files were ready for reading or writing (timeout)
>0 : Sum of the set bits of rfds and wfds
EIHNDL : At least one of the handles is not assigned to an open file
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

5.9.27.1 Bindings for Fselect

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

5.9.28 Fsetdta

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

5.9.28.1 Bindings for Fsetdta

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%)

5.9.29 Fsfirst

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:
Parameter Meaning
   
filename Pointer to the filename or subdirectory
attr Attributes that should be matched by the file searched for
Bit-0: Include read-only files
Bit-1: Include hidden files
Bit-2: Include system files
Bit-3: Include volume labels
Bit-4: Include subdirectories
Bit-5: Include files with archive-bit set


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:
(a) Best: use Dxreaddir
(b) Use only absolute symbolic links
(c) Alays make the search directory the current one


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:
E_OK : No error has occurred
EFILNF : File not found
ENMFIL : No more files
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fgetdta   Fsetdta   Fsnext   DTA   Recursive search   XFS-concept

5.9.29.1 Bindings for Fsfirst

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%)

5.9.30 Fsnext

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

5.9.30.1 Bindings for Fsnext

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)

5.9.31 Fsymlink

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:
E_OK : No error has arisen
EINVFN : The file-system does not support symbolic links
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

5.9.31.1 Bindings for Fsymlink

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

5.9.32 Fwrite

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:
Parameter Meaning
   
handle File handle identifier
count Number of bytes to be written
buf Start address of the buffer


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:
EACCDN : Access denied
EIHNDL : Invalid file handle
ELOCKED : File segment is marked as protected
Availability: All GEMDOS versions.
Group: File functions
See also: Binding   Fread   FIONWRITE

5.9.32.1 Bindings for Fwrite

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%)

5.9.33 Fxattr

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:
flag Meaning
   
0 Symbolic links are followed to the source file and the extended attributes are obtained from this file. (This corresponds to the procedure stat under UNIX).
1 The extended attributes of the symbolic link itself are obtained. (This corresponds to the procedure lstat under UNIX).


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:
E_OK : No error has arisen
EFILNF : File not found
EPTHNF : Path to file not found
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

5.9.33.1 Bindings for Fxattr

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

HomeGEMDOSgemdos-trapDate and Time