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 / d.src next >

Wrap

C/C++ Source or Header | 1993-02-04 | 14.6 KB | 406 lines

screen( capsensitive("Dclosedir")) NAME Dclosedir - close a directory SYNOPSIS LONG Dclosedir( LONG dirhandle ); DESCRIPTION Dclosedir closes the directory whose handle (returned from \#Dopendir\#) is dirhandle. RETURNS 0 on success EIHNDL if dirhandle is not valid SEE ALSO \#Dopendir\#, \#Dreaddir\# Last change: Oct. 1, 1991\end screen(capsensitive("Dcntl")) NAME Dcntl - perform a file system specific operation on a file or directory SYNOPSIS #include <filesys.h> LONG Dcntl(WORD cmd, char *name, LONG arg); DESCRIPTION Dcntl performs a file system specific command, given by cmd, upon the file or directory specified by name. The exact nature of the operation performed depends upon the file sys- tem on which name resides. The interpretation of the third argument arg depends upon the specific command. Dcntl commands are: \link("Dcntl commands")DEV_INSTALL\# \link("Dcntl commands")DEV_NEWTTY\# \link("Dcntl commands")DEV_NEWBIOS\# RETURNS The value returned depends on the specific operation requested and the file system involved. Generally, a 0 or positive return value should mean success, and a negative one failure. An exception is the value returned by DEV_INSTALL, which is either a pointer to a kernel informa- tion structure, or NULL on failure. SEE ALSO \#Bconmap\#, \#Fcntl\# Last change: Dec. 12, 1991\end screen("Dcntl commands") The only built-in file system which supports \#Dcntl\# opera- tions is the device file system U:\\DEV, which understands the following commands: DEV_INSTALL Installs a new device driver whose name is given by name (which must be the complete path and file name, e.g. U:\\DEV\\FOO). The device may be accessed only through GEMDOS file operations; the BIOS will not be aware of it. arg is a pointer to a \link("dev_descr")device descriptor\# structure. If the attempt to install the device is successful, Dcntl will return a pointer to a structure with type "struct kerinfo" that describes the kernel (see the documentation for loadable file systems for more infor- mation on this structure). This structure is in pro- tected memory and can be accessed only in supervisor mode. Moreover, the structure is read only; attempts to write to it will produce unpredictable errors. If there is not enough memory to install the new device, a null pointer will be returned. DEV_NEWTTY Installs a driver for a new BIOS terminal device whose name is name (this must be the full path name, e.g. U:\\DEV\\BAR). arg is the BIOS device number of this device. Note that the BIOS must have been told about the device already via the \#Bconmap\# system call or some similar mechanism; otherwise, any attempt to access the file will result in an unknown device error (EUNDEV). This command simply informs the kernel about a BIOS device that already exists, unlike DEV_INSTALL which actually creates a new device. DEV_NEWBIOS Installs a driver for a new BIOS non-terminal device whose name is name (this must be the full path name, e.g. U:\\DEV\\BAR). arg is the BIOS device number of this device. Note that the BIOS must have been told about the device already via the \#Bconmap\# system call or some similar mechanism; otherwise, any attempt to access the file will result in an unknown device error (EUNDEV). Like DEV_NEWTTY, this command informs the kernel of the existence of a BIOS device. The differ- ence between the two commands is that DEV_NEWTTY should be used for devices which may be used as terminal devices (e.g. serial lines), whereas DEV_NEWBIOS is useful for devices for which data must be always transmitted "raw" (e.g. a SCSI tape device, or perhaps a LAN device). Last change: Dec. 12, 1991\end screen("dev_descr") The device descriptor structure is used in a \link("Dcntl commands")DEV_INSTALL\# command in a \#Dcntl\# call. The dev_descr structure is defined in FILESYS.H: struct dev_descr { DEVDRV *driver; /* pointer to device driver structure */ short dinfo; /* placed in the "aux" field of file */ /* cookies */ short flags; /* either 0 or O_TTY */ struct tty *tty; /* if flags & O_TTY, this points to */ /* the tty structure associated with */ /* the device */ long reserved[4]; /* reserved for future expansion - */ /* set to 0 */ };\end screen( capsensitive("Dgetcwd")) NAME Dgetcwd - get current working directory for a process SYNOPSIS LONG Dgetcwd(char *path, WORD drv, WORD size); DESCRIPTION Dgetcwd may be used to retrieve the current working directory on the indicated drive for the current process. The directory is copied into the buffer pointed to by path, which is at least size bytes long. RETURNS 0 on success ERANGE if the supplied buffer is not long enough to hold the path EDRIVE if drv is not a valid GEMDOS drive. SEE ALSO \#Dgetpath\# Last change: Dec. 1, 1992\end screen(capsensitive("Dlock")) NAME Dlock - lock or unlock a BIOS disk device SYNOPSIS LONG Dlock( WORD mode, WORD drv ); DESCRIPTION Dlock is used to lock or unlock the BIOS device indicated by drv. No GEMDOS file operations are permitted on a locked drive. Thus, the Dlock call provides a mechanism for disk formatters or re-organizers to lock out other processes while low-level BIOS or XBIOS operations are in progress on the device. If bit 0 of mode is 1, the drive is locked; if it is 0 then the drive is unlocked and may be used again by other programs. If a process terminates while holding a lock on a drive, that drive is automatically unlocked. Bit 1 of mode indicates what return values are desired. If this bit is 1, and if the drive is locked by a user process different from the caller, or if some process has files open on the drive, then that process' id will be returned (see below). This may be used to report a more useful error message to the user (by telling him or her which process is using the drive in question when a lock operation fails). All other bits of mode are reserved and must be set to 0. A lock operation followed immediately by an unlock is very similar to a media change, except that the lock operation will fail if there are open files that refer to the indicated drive. RETURNS 0 if the lock/unlock operation was successful EDRIVE if drv is not a valid BIOS device number For a lock operation, the following error codes may be returned: A positive process id if bit 1 of mode is set, and the drive is already locked or in use by another user process. EACCDN if bit 1 of mode is clear and either open files exist on the drive or another process is searching a directory on the drive, or if bit 1 of mode is set and the drive is in use by the operating system. ELOCKED if bit 1 of mode is clear and another process has locked the drive, or if bit 1 of mode is set and the operating system has locked the drive. For an unlock operation the following error codes may be returned: ENSLOCK if mode is 0 and the drive was not locked by this process. SEE ALSO \#Fxattr\# NOTES Note that Dlock operates on BIOS devices, which may not always be in 1-1 correspondence with GEMDOS drive letters. For this reason, to lock GEMDOS drive A: (for example), the programmer should call \#Fxattr\# on the root directory of A: ("A:\\e") and then use the dev field of the structure returned in order to determine the BIOS device corresponding to the GEMDOS drive. BUGS All GEMDOS operations are forbidden on a locked drive, even by the process that created the lock. It would be useful to have a mode which allowed the locking process (and only the locking process) to still make GEMDOS calls on the drive, but unfortunately the structure of the OS makes this difficult; there is also the above-mentioned difference between BIOS and GEMDOS devices to consider. Last change: Jan. 8, 1993\end screen(capsensitive("Dopendir")) NAME Dopendir - open a directory for reading SYNOPSIS LONG Dopendir(char *name, WORD flag); DESCRIPTION Dopendir opens the directory whose name is pointed to by name for reading. A 32 bit directory handle is returned which may be passed to Dreaddir to actually read the direc- tory. flag controls the way directory operations are per- formed. If flag == 1, then the directory is read in "compa- tibility" mode, if flag == 0 then directory operations are performed in "normal" mode. In "compatibility" mode, file systems act as if the \#Fsfirst\# and \#Fsnext\# functions were being used; in particular, if it is possible file names will be restricted to the DOS 8 character name + 3 character extension convention, and will be in upper case. In "normal" mode, file systems do not attempt to restrict the range of names. Moreover, in this mode the \#Dreaddir\# system call will also return a file index number (similar to the Unix inode number) along with the file name. New programs should generally use normal mode where possi- ble. RETURNS A 32 bit directory handle, on success. Note that this handle may be negative, but will never contain the pattern 0xFF in the upper byte, whereas all errors do contain this pat- tern in the upper byte. EPTHNF if name is not a valid directory EACCDN if the directory is not accessible by this program ENSMEM if the kernel is unable to allocate memory needed for the directory operations SEE ALSO \#Dclosedir\#, \#Dreaddir\#, \#Drewinddir\# BUGS With every Dopendir call, some kernel memory is allocated that is only freed when \#Dclosedir\# is called or the process exits. Therefore, every long-running program that calls Dopendir should always make corresponding calls to \#Dclosedir\#. Last change: Jan. 8, 1993\end screen(capsensitive("Dpathconf")) NAME Dpathconf - get information about file system configuration SYNOPSIS LONG Dpathconf(char *name, WORD mode); DESCRIPTION Dpathconf returns information about various limits or capa- bilities of the file system containing the file named name. The variable mode controls which limit or capability is being queried, as follows: mode Value Returned -1 return max. legal value for n in Dpathconf(n) 0 return internal limit on the number of open files 1 return max. number of links to a file 2 return max. length of a full path name 3 return max. length of an individual file name 4 return number of bytes that can be written atomically 5 return information about file name truncation If any of these items are unlimited, then 0x7fffffffL is returned. For mode 5, return information about file name truncation, the returned value has the following meaning: 0 File names are never truncated; if the file name in any system call affecting this directory exceeds the max- imum length (returned by mode 3), then the error value ERANGE is returned from that system call. 1 File names are automatically truncated to the maximum length. 2 File names are truncated according to DOS rules, i.e. to a maximum 8 character base name and a maximum 3 character extension. SEE ALSO \#Sysconf\# Last change: Oct. 1, 1991\end screen(capsensitive("Dreaddir")) NAME Dreaddir - read directory information SYNOPSIS LONG Dreaddir(WORD len, LONG dirhandle, char *buf); DESCRIPTION Dreaddir returns the next file in the directory whose handle (from the \#Dopendir\# system call) is dirhandle. The file's name and (optionally) a 4 byte index for the file are placed in the buffer pointed to by buf. The file index is omitted if the directory was opened in "compatibility" mode (see \#Dopendir\# for details); otherwise, it is placed first in the buffer, followed by the (null terminated) name. If two names have the same index, then they refer to the same file; the converse, however, is not true. len is the size of the buffer, in total; it should be large enough to hold the index (if any), the file name, and the trailing 0. Successive calls to Dreaddir will return all the names in the directory, one after another, unless the Drewinddir sys- tem call is used to restart the reading at the beginning of the directory. RETURNS 0 if successful ERANGE if the buffer was not large enough to hold the index (if present) and name ENMFIL if there are no more file names to be read from the directory SEE ALSO \#Dclosedir\#, \#Dopendir\#, \#Drewinddir\# BUGS Failure to call Dclosedir() when the search is done could result in the system eventually running out of file indices; this is fatal. So always call Dclosedir() when you're fin- ished with the directory search! Last change: Oct. 1, 1991\end screen(capsensitive("Drewinddir")) NAME Drewinddir - rewind an open directory SYNOPSIS LONG Drewinddir(LONG handle); DESCRIPTION Drewinddir rewinds the open directory whose handle (returned from the \#Dopendir\# system call) is handle. After the Drewinddir call, the next call to \#Dreaddir\# will read the first file in the directory. RETURNS 0 on success EIHNDL if handle does not refer to a valid open directory EINVFN if the directory cannot be rewound (for example, because of the type of file system on which it is located) SEE ALSO \#Dopendir\#, \#Dreaddir\# Last change: Oct. 1, 1991\end