The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / pure_src / f.src < prev next >

Wrap

Text File | 1993-02-17 | 35.2 KB | 1,070 lines

screen(capsensitive("Fchmod")) NAME Fchmod - set file access permissions SYNOPSIS #include <filesys.h> LONG Fchmod(char *name, WORD mode); DESCRIPTION Fchmod changes the file access permissions for the file named name. The new access permissions are given in the word mode, which may be constructed by or'ing together the following symbolic constants (defined in filesys.h): S_IRUSR, Read, write, and execute permission (respectively) for the owner of the file. S_IRGRP, Read, write, and execute permission (respectively) for the file's group. S_IROTH, Read, write, and execute permission for everybody else. Note that not all file systems support all of these bits; bits not supported by a file system will be ignored. Note also that "execute" permission for a directory means permission to search the directory for a file name or name component. RETURNS 0 on success EACCDN if the calling process has an effective uid which differs from the owner of the file and which is not 0. EFILNF if the file is not found. EPTHNF if the path to the file is not found. SEE ALSO \#Fattrib\#, \#Fxattr\# Last change: Oct. 7, 1991\end screen(capsensitive("Fchown")) NAME Fchown - change a file's ownership SYNOPSIS LONG Fchown(char *name, WORD uid, WORD gid); DESCRIPTION Fchown changes a file's user and group ownership to uid and gid respectively. These ownerships determine access rights to the file. Only a process with effective uid 0 or whose effective uid matches the user ownership of the file may make this call. In the latter case, the new uid must match the old one, and the calling process must also be a member of the group specified by gid. RETURNS 0 on success EACCDN if the calling process has an effective uid which differs from the owner of the file and which is not 0. EINVFN if the file system on which the file is located does not support a notion of ownership. (This is true of the normal TOS file system.) EFILNF if the file is not found. EPTHNF if the path to the file is not found. SEE ALSO \#Fchmod\#, \#Fxattr\# BUGS Most file systems don't understand file ownership. In practice, the call is useful only to processes with effective uid 0. Last change: Dec. 12, 1991\end screen(capsensitive("Fcntl")) NAME Fcntl - perform various control operations on a file SYNOPSIS #include <filesys.h> LONG Fcntl(WORD fh, LONG arg, WORD cmd); DESCRIPTION Fcntl performs various control operations on the open file with GEMDOS file handle fh. The specific command to perform is given by cmd; the possible commands are given by symbolic constants in filesys.h, and are listed below. arg is an argument whose meaning depends on the command. The following commands are applicable to any file descriptor: \link("Fcntl file commands")F_DUPFD\# \link("Fcntl file commands")F_GETFD\# \link("Fcntl file commands")F_SETFD\# \link("Fcntl file commands")F_GETFL\# \link("Fcntl file commands")F_SETFL\# \link("Fcntl file commands")F_GETLK\# \link("Fcntl file commands")F_SETLK\# \link("Fcntl file commands")F_SETLKW\# \link("Fcntl file commands")FSTAT\# \link("Fcntl file commands")FIONREAD\# \link("Fcntl file commands")FIONWRITE\# The following commands are valid for any terminal device, e.g. the console or a pseudo-terminal: \link("Fcntl terminal commands")TIOCGETP\# \link("Fcntl terminal commands")TIOCSETP\# \link("Fcntl terminal commands")TIOCGETC\# \link("Fcntl terminal commands")TIOCSETC\# \link("Fcntl terminal commands")TIOCGLTC\# \link("Fcntl terminal commands")TIOCSLTC\# \link("Fcntl terminal commands")TIOCGWINSZ\# \link("Fcntl terminal commands")TIOCSWINSZ\# \link("Fcntl terminal commands")TIOCGPGRP\# \link("Fcntl terminal commands")TIOCSPGRP\# \link("Fcntl terminal commands")TIOCSTART\# \link("Fcntl terminal commands")TIOCSTOP\# \link("Fcntl terminal commands")TIOCGXKEY\# \link("Fcntl terminal commands")TIOCSXKEY\# The following commands are valid only for processes opened as files: \link("Fcntl process commands")PBASEADDR\# \link("Fcntl process commands")PPROCADDR\# \link("Fcntl process commands")PCTXTSIZE\# The following commands are valid only for files which represent shared memory: \link("Fcntl shared memory commands")SHMSETBLK\# \link("Fcntl shared memory commands")SHMGETBLK\# RETURNS 0 or a positive number if successful (for most commands, 0, but see the specific descriptions above). EIHNDL if fh is not a valid GEMDOS open handle. EINVFN if the specified command is not valid for this file handle. Some other (LONG) negative error number if an error occurs; different commands may recognize different possible errors. SEE ALSO \#Fdup\#, \#Flock\#, \#Fopen\#, \#Fxattr\#, \#Pgetpgrp\#, \#Psetpgrp\# BUGS Very little error checking is done. In particular, ownership of terminals is not properly checked, nor is read/write access to the files. Do not rely on this bug; it will be fixed some day. File locking is not yet implemented for most file systems. Very few of the terminal control options have effect on ter- minals connected via serial ports or midi. In particular, it is not possible to set the baud rate, parity, flow control, or similar options with Fcntl. However, this bug will be fixed in future versions of the operating system, so pro- grams should never modify the sg_ispeed, sg_ospeed, or sg_flags fields of the \link("struct sgttyb")sgttyb structure\#, and should always use TIOCGETP to obtain the original settings of these fields before calling TIOCSETP. Last change: July 20, 1992\end screen("Fcntl file commands") The following \#Fcntl\# commands are applicable to any file descriptor: F_DUPFD Return a duplicate for the file handle. The new (dupli- cate) handle will be an integer >= arg and < 32. If no free handles exist in that range, ENHNDL will be returned. The \#Fdup\# system call is equivalent to Fcntl(fh, 6L, F_DUPFD) F_GETFD Return the noinherit flag for the file descriptor. This flag is 1 if child processes started by Pexec should inherit this open file, and 0 if not. arg is ignored. F_SETFD Set the noinherit flag for the file descriptor from the low order bit of arg. The default value of the flag is 0 for handles 0-5 (the "standard" handles) and 1 for other (non-standard) handles. Note that the noinherit flag applies only to this particular file descriptor; another descriptor obtained from fh by the \#Fdup\# system call or by use of the F_DUPFD option to \#Fcntl\# will have the noinherit flag set to the default. Also note that these defaults are not the same as for the Unix operat- ing system. F_GETFL Returns the user-settable file descriptor flags. These flags are the same as the mode passed to \#Fopen\#, unless they have been further modified by another \#Fcntl\# opera- tion. arg is ignored. F_SETFL Set user-settable file descriptor flags from the argu- ment arg. Only the user-settable bits in arg are con- sidered; the settings of other bits are ignored, but should be 0 for future compatibility. Moreover, it is not possible to change a file's read-write mode or sharing modes with this call; attempts to do so will (silently) fail. F_GETLK arg is a pointer to an \link("struct flock")flock structure\#. If a lock exists which would prevent this lock from being applied to the file, the existing lock is copied into the structure and the l_pid field is set to the process id of the locking process. Otherwise, l_type is set to F_UNLCK. If a conflicting lock is held by a pro- cess on a different machine on a network, then the l_pid field will be set to a value defined by the net- work file system. This value will be in the range 0x1000 to 0xFFFF, and will therefore not conflict with any process id since process id's must be less than 0x1000. F_SETLK Set (if l_type is F_RDLCK or F_WRLCK) or clear (if l_type is F_UNLCK) an advisory lock on a file. If the file is a FIFO, the whole file must be locked or unlocked at once, i.e. l_whence, l_start, and l_len must be 0. If this lock would conflict with a lock held by another process, ELOCKED is returned. If an attempt is made to clear a non-existent lock, ENSLOCK is returned. More than one read lock may be placed on the same region of a file, but no write lock may overlap with any other sort of lock. If a process holds locks on a file, then the locks are automatically released whenever the process closes an open file handle referring to that file, or when the process terminates. F_SETLKW Similar to F_SETLK, but will never fail on a legal request; the process will be blocked until the lock can be obtained. Note: this mode has not been documented yet by Eric Smith! FSTAT arg points to an XATTR structure, which is filled in with the appropriate extended file attributes for the file to which fd refers just as though the \#Fxattr\# system call had been made on the file. FIONREAD arg points to a 32 bit integer, into which is written the number of bytes that are currently available to be read from this descriptor; a read of this number of bytes or less should not cause the process to block (wait for more input). Note that for some files only an estimate can be provided, so the number is not always completely accurate. FIONWRITE arg points to a 32 bit integer, into which is written the number of bytes that may be written to the indi- cated file descriptor without causing the process to block. Note that for some files only an estimate can be provided, so the number is not always completely accurate. Last change: July 20, 1992\end screen("struct flock") The file lock structure is used in a \link("Fcntl file commands")F_GETLK\# or \link("Fcntl file commands")F_SETLK\# command in a \#Fcntl\# call. The flock structure is defined in FILESYS.H: struct flock { short l_type; /* type of lock */ #define F_RDLCK 0 #define F_WRLCK 1 #define F_UNLCK 3 short l_whence; /* 0:file start, 1:current, 2:EOF */ long l_start; /* offset of locked region */ long l_len; /* 0 for rest of file */ short l_pid; /* set by F_GETLK */ };\end screen("Fcntl terminal commands") The following \#Fcntl\# commands are valid for any terminal device, e.g. the console or a pseudo-terminal: TIOCGETP Get terminal parameters from the \link("struct sgttyb")terminal description\# \link("struct sgttyb")structure\# pointed to by arg. TIOCSETP Set terminal parameters from the \#struct sgttyb\# pointed to by arg. TIOCGETC Get terminal control characters. arg is a pointer to a \link("struct tchars")terminal control structure\#. TIOCSETC Set terminal control characters from the \#struct tchars\# pointed to by arg. Setting any character to the value 0 causes the corresponding function to become unavail- able. TIOCGLTC Get extended terminal control characters, and put them in the \link("struct ltchars")ltchars structure\# pointed to by arg. TIOCSLTC Set extended terminal control characters from the \#struct ltchars\# pointed to by arg. Setting any of the characters to 0 causes the corresponding function to become unavailable. TIOCGWINSZ arg has type \link("struct winsize")struct winsize *\#. The current window size for this window is placed in the structure pointed to by arg. TIOCSWINSZ arg has type \link("struct winsize")struct winsize *\#. The current window size for the window is set from the structure pointed to by arg. Note that the kernel maintains the informa- tion but does not act upon it in any way; it is up to window managers to perform whatever physical changes are necessary to alter the window size, and to raise the SIGWINCH signal if necessary. TIOCGPGRP arg has type "long *"; the process group for the termi- nal is placed into the long pointed to by it. TIOCSPGRP arg has type "long *"; the process group for the termi- nal is set from the long pointed to by it. Processes in any other process group will be sent job control sig- nals if they attempt input or output to the terminal. TIOCSTART Restart output to the terminal (as though the user typed control-Q) if it was stopped by a control-S or TIOCSTOP command. arg is ignored. TIOCSTOP Stop output to the terminal (as though the user typed control-S). arg is ignored. TIOCGXKEY Get the definition of a function or cursor key. arg is a pointer to an \link("struct xkey")xkey structure\#. TIOCSXKEY arg is a structure of type \#struct xkey\#, as defined above. Both the xk_num and the xk_def fields must be defined. After execution of this command, and if the XKEY bit is set in the sg_flags field of the \link("struct sgttyb")sgttyb\# \link("struct sgttyb")structure\# associated with the terminal, then if the indicated key is pressed on the affected terminal, any MiNT domain process using \#Fread\# to read the key will get the string in xk_def instead of ASCII 0. Note that this translation occurs only for MiNT domain processes and only for the \#Fread\# system call. Also note that the string in xk_def must be null terminated, and so at most 7 characters may be assigned to any key. Last change: July 20, 1992\end screen("struct sgttyb") The terminal description structure is used in a \link("Fcntl terminal commands")TIOCGETP\# or \link("Fcntl terminal commands")TIOCSETP\# command in a \#Fcntl\# call. The sgttyb structure is defined in FILESYS.H: struct sgttyb { char sg_ispeed; /* reserved */ char sg_ospeed; /* reserved */ char sg_erase; /* erase character */ char sg_kill; /* line kill character */ short sg_flags; /* terminal control flags */ };\end screen("struct tchars") The terminal control structure is used in a \link("Fcntl terminal commands")TIOCGETC\# or \link("Fcntl terminal commands")TIOCSETC\# command in a \#Fcntl\# call. The tchars structure is defined in FILESYS.H: struct tchars { char t_intrc; /* raises SIGINT */ char t_quitc; /* raises SIGQUIT */ char t_startc; /* starts terminal output */ char t_stopc; /* stops terminal output */ char t_eofc; /* marks end of file */ char t_brkc; /* marks end of line */ };\end screen("struct ltchars") The extended terminal control structure is used in a \link("Fcntl terminal commands")TIOCGLTC\# or \link("Fcntl terminal commands")TIOCSLTC\# command in a \#Fcntl\# call. The ltchars structure is defined in FILESYS.H: struct ltchars { char t_suspc; /* raises SIGTSTP now */ char t_dsuspc; /* raises SIGTSTP when read */ char t_rprntc; /* redraws the input line */ char t_flushc; /* flushes output */ char t_werasc; /* erases a word */ char t_lnextc; /* quotes a character */ };\end screen("struct winsize") The window size structure is used in a \link("Fcntl terminal commands")TIOCGWINSZ\# or \link("Fcntl terminal commands")TIOCSWINSZ\# command in a \#Fcntl\# call. The winsize structure is defined in FILESYS.H: struct winsize { short ws_row; /* # of rows of text in window */ short ws_col; /* # of columns of text */ short ws_xpixel; /* width of window in pixels */ short ws_ypixel; /* height of window in pixels */ }; If any fields in the structure are 0, this means that the corresponding value is unknown.\end screen("struct xkey") The key definition structure is used in a \link("Fcntl terminal commands")TIOCGXKEY\# or \link("Fcntl terminal commands")TIOCSXKEY\# command in a \#Fcntl\# call. The xkey structure is defined in FILESYS.H: struct xkey { short xk_num; /* function key number */ char xk_def[8]; /* associated string */ }; The xk_num field must be initialized with the number of the desired key: xk_num Key 0-9 F1-F10 10-19 F11-F20 (shift F1-shift F10) 20 cursor up 21 cursor down 22 cursor right 23 cursor left 24 help 25 undo 26 insert 27 clr/home 28 shift+cursor up 29 shift+cursor down 30 shift+cursor right 31 shift+cursor left The string currently associated with the indicated key is copied into xk_def; this string is always nullterminated.\end screen("Fcntl process commands") The following \#Fcntl\# commands are valid only for processes opened as files: PBASEADDR arg is a pointer to a 32 bit integer, into which the address of the process basepage for the process to which fh refers is written. PPROCADDR arg is a pointer to a 32 bit integer, into which the address of the process control structure for the pro- cess is written. Note that this control structure differs from the one found in previous versions (before 0.93) of MiNT; it no longer includes the process con- text, so that this part of the structure may be changed without causing compatibility problems. See the PCTXTSIZE command. PCTXTSIZE arg is a pointer to a 32 bit integer, into which the length of a process context structure is written. There are two of these structures located in memory just before the process control structure whose address is returned by the PPROCADDR command. The first is the current process context; the second is the saved con- text from the last system call. Last change: July 20, 1992\end screen(capsensitive("Fcntl shared memory commands")) The following \#Fcntl\# commands are valid only for files which represent shared memory: SHMSETBLK arg is a pointer to a block of memory previously allocated by \#Mxalloc\#. The memory will be offered for sharing under the name of the file represented by fd (which must be a file in the U:\\SHM directory). SHMGETBLK arg must be 0, for future compatibility. Returns the address of the block of memory previously associated with the file via SHMSETBLK, or a NULL pointer if an error occurs. Note that different processes may see the shared memory block at different addresses in their address spaces. Therefore, the shared memory block should not contain any absolute pointers to data. Last change: July 20, 1992\end screen(capsensitive("Fgetchar")) NAME Fgetchar - read a character from a file SYNOPSIS LONG Fgetchar(WORD fh, WORD mode); DESCRIPTION Fgetchar reads a character from the open file whose handle is fh. The parameter mode has an effect only if the open file is a terminal or pseudo-terminal, in which case the bits of mode have the following meanings: 0x0001 Cooked mode; special control characters (control-C and control-Z) are checked for and interpreted if found (they cause SIGINT and SIGTSTP, respectively, to be raised); also, flow control with control-S and control-Q is activated. 0x0002 Echo mode; characters read are echoed back to the ter- minal. The ASCII value of the character read is put in the low byte of the long word that is returned. If the file is a terminal or pseudo-terminal, the scan code of the character pressed and (possibly) the shift key status are also returned in the long word, just as with the BIOS \#Bconin\# system call. RETURNS The character read, if successful. 0x0000FF1A if end of file is detected. EIHNDL if fh is not a valid handle for an open file. SEE ALSO \#Bconin\#, \#Cconin\#, \#Cauxin\#, \#Fputchar\#, \#Fread\# Last change: Oct. 1, 1991\end screen(capsensitive("Finstat")) NAME Finstat - determine input status for a file SYNOPSIS LONG Finstat(WORD fh); DESCRIPTION Finstat returns the number of bytes of input waiting on the file whose GEMDOS handle is fh, or 0 if no input is avail- able on that handle. RETURNS 0 or a positive number if successful EIHNDL if fh is not a valid handle for an open file. SEE ALSO \#Cauxis\#, \#Cconis\#, \#Fcntl\#, \#Foutstat\# BUGS Always returns 1 for disk files. Doesn't check to see if the indicated file was opened for reading. Last change: Oct. 1, 1991\end screen(capsensitive("Flink")) NAME Flink - create a new link to a file SYNOPSIS LONG Flink(char *oldname, char *newname); DESCRIPTION Flink creates a new name (a "hard link") for the file currently named oldname. If the Flink call is successful, then after the call the file may be referred to by either name, and a call to \#Fdelete\# on either name will not affect access to the file through the other name. oldname and newname must both refer to files on the same physical dev- ice. Note also that not all file systems allow links. RETURNS 0 on success EXDEV if oldname and newname refer to files on different physical devices EINVFN if the file system does not allow hard links EFILNF if the file named oldname does not currently exist SEE ALSO \#Frename\#, \#Fsymlink\# Last change: Oct. 7, 1991\end screen(capsensitive("Fmidipipe")) NAME Fmidipipe - redirect MIDI input and output SYNOPSIS LONG Fmidipipe(WORD pid, WORD in, WORD out); DESCRIPTION Fmidipipe changes the MIDI input and output file handles (GEMDOS file handles -4 and -5 respectively) for process pid. in is the GEMDOS handle (for the calling process) which will become the MIDI input for the receiving process, and out is the GEMDOS handle which is to become the MIDI output. If pid is 0, then the call affects the current process; in this case, it is roughly equivalent to the sequence Fforce(-4, in); Fforce(-5, out); RETURNS 0 on success EFILNF if the indicated process is not found EIHNDL if either in or out is not a valid open handle. EACCDN if in is not open for reading or if out is not open for writing. SEE ALSO \#Fdup\#, \#Fforce\# BUGS Any user can change the MIDI input and output of any pro- cess. This will eventually be corrected. Last change: Oct. 1, 1991\end screen(capsensitive("Foutstat")) NAME Foutstat - determine output status for a file SYNOPSIS LONG Foutstat(WORD fh); DESCRIPTION Foutstat returns the number of bytes of output that may be written to the file whose GEMDOS handle is fh, without blocking. RETURNS 0 or a positive number if successful EIHNDL if fh is not a valid handle for an open file. SEE ALSO \#Cauxos\#, \#Cconos\#, \#Cprnos\#, \#Fcntl\#, \#Finstat\# BUGS Always returns 1 for disk files. Doesn't check to see if the indicated file was opened for writing. Last Change: Oct. 1, 1991\end screen(capsensitive("Fpipe")) NAME Fpipe - create a pipe SYNOPSIS LONG Fpipe(WORD usrh[2]); DESCRIPTION Fpipe creates a pipe that may be used for interprocess com- munication. If it is successful, two GEMDOS handles are returned in usrh[0] and usrh[1]. usrh[0] will contain a han- dle for the read end of the pipe, (opened for reading only), and usrh[1] will contain a handle for the write end of the pipe (opened for writing only). The created pipe has the name "sys$pipe.xxx", where "xxx" is a three digit integer. USAGE Typically used by shells; the shell redirects its standard input (or standard output) to the read (or write) end of the pipe using \#Fdup\# and \#Fforce\# before launching a child; the child will then read from (or write to) the pipe by default. RETURNS 0 if successful ENHNDL if there are not 2 free handles to allocate for the pipe ENSMEM if there is not enough free memory to create the pipe EACCDN if too many pipes already exist in the system BUGS There cannot be more than 999 open pipes in the system at one time. Last change: Oct. 1, 1991\end screen(capsensitive("Fputchar")) NAME Fputchar - read a character from a file SYNOPSIS LONG Fputchar(WORD fh, LONG ch, WORD mode); DESCRIPTION Fputchar outputs a character to the GEMDOS file whose handle is fh. The parameter mode has an effect only if the open file is a terminal or pseudo-terminal, in which case the bits of mode have the following meanings: 0x0001 Cooked mode; special control characters (control-C and control-Z) are checked for and interpreted if found (they cause SIGINT and SIGTSTP, respectively, to be raised); also, flow control with control-S and control-Q is activated. If the file receiving output is a pseudo-terminal, then all 4 bytes of ch are recorded in the write, and may be retreived by a Fputchar call on the other side of the pseudo-terminal; this allows programs to pass simulated BIOS scan codes and shift key status through the pseudo-terminal. If the file receiving output is not a terminal, then only the low order byte of ch is written to the file. RETURNS 4 (the number of bytes of data transferred) if the write was to a terminal 1 if the write was not to a terminal and was successful 0 if the bytes could not be output (for example, because of flow control) EIHNDL if fh is not a valid handle for an open file. A (long) negative BIOS error code if an error occured during physical I/O. SEE ALSO \#Bconout\#, \#Cauxout\#, \#Cconout\#, \#Crawio\#, \#Fgetchar\#, \#Fwrite\# Last change: Oct. 1, 1991\end screen(capsensitive("Freadlink")) NAME Freadlink - determine contents of a symbolic link SYNOPSIS LONG Freadlink(WORD bufsiz, char *buf, char *name); DESCRIPTION Freadlink determines what file the symbolic link name points to, i.e. what the first argument to the \#Fsymlink\# call that created name was. This 0-terminated string is placed in the memory region pointed to by buf. The total size of this region is given by bufsiz; this must be enough to hold the terminating 0. RETURNS 0 on success ERANGE if the symbolic link contents could not fit in buf. EFILNF if name is not found. EACCDN if name is not the name of a symbolic link. EINVFN if the file system containing name does not support symbolic links. SEE ALSO \#Fsymlink\# BUGS The Unix readlink call returns the number of bytes read on success, rather than 0. Last change: Oct. 7, 1992\end screen(capsensitive("Fselect")) NAME Fselect - select file descriptors that are ready for reading or writing SYNOPSIS WORD Fselect(WORD timeout, LONG *rfds, LONG *wfds, ((long)0)); DESCRIPTION Fselect checks two sets of open file descriptors and deter- mines which have data ready to read, and/or which are ready to be written to. If none are ready yet, the process goes to sleep until some member of the sets are ready or until a specified amount of time has elapsed. rfds points to a long word which represents a set of GEMDOS file descriptors; bit n of this long word is set if file descriptor n is to be checked for input data. An empty set may optionally be represented by a NULL pointer instead of a pointer to 0. Similarly, wfds points to a 32 bit long word which indicates which file descriptors are to be checked for output status. When Fselect returns, the old values pointed to by rfds and wfds (if non-NULL) are overwritten by new long words indicating which file descriptors are actually ready for reading or writing; these will always form subsets of the file descriptors originally specified as being of interest. timeout is a 16 bit unsigned integer specifying a maximum number of milliseconds to wait before returning; if this number is 0, no maximum is set and the call will block until one of the file descriptors specified is ready for reading or writing, as appropriate. Thus, Fselect(0,0L,0L,0L) will block forever, whereas Fselect(1,0L,0L,0L) will pause for 1 millisecond. The final argument, a long word, must always be 0 (it is reserved for future enhancements). RETURNS The sum of the numbers of bits set in the long words pointed to by rfds and wfds. This will be 0 if the timeout expires without any of the specified file descriptors becoming ready for reading or writing, as appropriate, and nonzero other- wise. EIHNDL if any handle specified by the long words pointed to by rfds or wfds is not a valid (open) GEMDOS handle. SEE ALSO \#Finstat\#, \#Foutstat\# BUGS The system timer is not actually accurate to the nearest millisecond, so the timeout could last for up to 19 mil- liseconds longer than specified. Fselect does not work correctly on any BIOS device except the keyboard. Note that if an error condition occurs on one of the file descriptors (for example, if the read status of a pipe with no more writers is being requested) then Fselect will mark that file descriptor as being ready for reading (or writing, as appropriate). This is not strictly speaking a bug, since a subsequent read will not block (it will return an error condition), but programmers should be aware of the possibil- ity. Last change: Oct. 1, 1991\end screen(capsensitive("Fsymlink")) NAME Fsymlink - create a symbolic link to a file SYNOPSIS LONG Fsymlink(char *oldname, char *newname); DESCRIPTION Fsymlink creates a new symbolic link (a "soft link") for the file currently named oldname. If the Fsymlink call is suc- cessful, then after the call the file may be referred to by either name. A call to \#Fdelete\# on the new name will not affect the existence of the file, just of the symbolic link. A a call to \#Fdelete\# with the name oldname will actually delete the file, and future references with newname will fail. Unlike hard links, symbolic links may be made between files on different devices or even different types of file systems. RETURNS 0 on success EINVFN if the file system does not allow symbolic links An appropriate error code if the new symbolic link cannot be created. SEE ALSO \#Flink\#, \#Freadlink\#, \#Frename\# BUGS No check is made for the existence of the file named old- name; this could be construed as a feature. Last change: Oct. 7, 1991\end screen(capsensitive("Fxattr")) NAME Fxattr - get extended attributes for a file SYNOPSIS #include <filesys.h> LONG Fxattr(WORD flag, char *name, XATTR *xattr); DESCRIPTION Fxattr gets file attributes for the file named name and stores them in the structure pointed to by xattr. This structure is defined in the file filesys.h, and contains the following fields of interest: unsigned short mode This field gives the file type and access permissions; (mode & S_IFMT) gives the file type (one of S_IFCHR, S_IFDIR, S_IFREG, S_IFIFO, S_IMEM, or S_IFLNK); (mode & ~S_IFMT) gives the file access mode according to the POSIX standard. See filesys.h for the definitions and meanings of the constants. long index An index for the file. Together with the "dev" field, this is intended to give a unique way of identifying the file. Note, however, that not all file systems are able to support this meaning, so it is best not to use this field unless absolutely necessary. unsigned short dev The device number for the file. This may be a BIOS device number as passed to the \#Rwabs\# function, or it may be a device number concocted by the file system to represent a remote device. unsigned short nlink Number of hard links to the file. Normally this field will be 1. unsigned short uid The user id of the owner of the file. unsigned short gid The group id of the owner of the file. long size The length of the file, in bytes. long blksize The size of blocks on this file system. long nblocks The number of physical blocks occupied by the file on the disk; this count includes any blocks that have been reserved for the file but do not yet have data in them, and any blocks that the file system uses internally to keep track of file data (e.g. Unix indirect blocks). short mtime The time of the last modification to the file, in stan- dard GEMDOS format. short mdate The date of the last modification, in standard GEMDOS format. short atime, adate The time and date of the last access to the file, in GEMDOS format. Filesystems that do not keep this time will return the values given in "mtime" and "mdate" for these fields as well. short ctime, cdate The time and date of the file's creation, in GEMDOS format. Filesystems that do not keep this time will return the values given in "mtime" and "mdate" for these fields as well. short attr The standard TOS attributes for the file, as returned by \#Fattrib\# and/or \#Fsfirst\#. The flag parameter controls whether or not symbolic links should be followed. If it is 0, then symbolic links are fol- lowed (like the Unix stat function). If flag is 1, then links are not followed and the information returned is for the symbolic link itself (if the named file is a symbolic link); this behavior is like that of the Unix lstat system call. RETURNS 0 on success EFILNF if the file is not found EPTHNF if the path to the file is not found. SEE ALSO \#Fattrib\#, \#Fsnext\# Last change: Oct. 1, 1991\end