Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileLoadable File SystemsMiNT supports loadable file systems to provide support for those other
than TOS (such as POSIX, HPFS, ISO 9660 CD-ROM, etc.) The MiNT kernel will
automatically load file system '.XFS' executables found in the \MULTITOS
or root directory. As of MiNT version 1.08, it is also possible to have
a TSRTermitate and Stay Resident programm
program install a file system with the Dcntl() call.
When the file system is executed by MiNT (i.e. not via Dcntl()), MiNTcreates an 8K stack and shrinks the TPA so a call to Mshrink() is not
necessary. The first instruction of the code segment of the file is JSR'ed
to with a pointer to a kerinfo (as defined above) structure at 4(sp). The
file system should use this entry point to ensure that it is running on
the minimum version of MiNT needed and that any other aspects of the
system are what is required for the file system to operate.
It is not necessary to scan existing drives to determine if they are
compatible with the file system as that is accomplished with the file
system root() function (defined below). If the file system needs to make
MiNT aware of drives that would not be automatically recognized by the
system, it should update the longword variable _drvbits at location 0x04F2
appropriately.
If the file system was unable to initialize itself or the host system is
incapable of supporting it, the entry stub should return with a value of
0L in d0. If the file system installs successfully, it should return
a pointer to a FILESYS (defined below) structure in d0. A file system
should never call Pterm() or Ptermres().
All file system functions, including the entry stub, must preserve
registers d2-d7 and a2-a7. Any return values should be returned in d0.
Function arguments are passed on the stack. The following listing defines
the FILESYS structure:
typedef struct filesys
{
struct filesys *next;
LONG fsflags;
LONG (*root)( WORD drv, fcookie *fc );
LONG (*lookup)( fcookie *dir, char *name, fcookie *fc );
LONG (*creat)( fcookie *dir, char *name, UWORD mode,
WORD attrib, fcookie *fc );
DEVDRV *(*getdev)( fcookie *fc, LONG *devspecial );
LONG (*getxattr)( fcookie *file, XATTR *xattr );
LONG (*chattr)( fcookie *file, WORD attr );
LONG (*chown)( fcookie *file, WORD uid, WORD gid );
LONG (*chmode)( fcookie *file, WORD mode );
LONG (*mkdir)( fcookie *dir, char *name, UWORD mode );
LONG (*rmdir)( fcookie *dir, char *name );
LONG (*remove)( fcookie *dir, char *name );
LONG (*getname)( fcookie *relto, fcookie *dir, char *pathname );
LONG (*rename)( fcookie *olddir, fcookie *oldname,
fcookie *newdir, fcookie *newname );
LONG (*opendir)( DIR *dirh, WORD tosflag );
LONG (*readdir)( DIR *dirh, char *name, WORD namelen,
fcookie *fc );
LONG (*rewinddir)( DIR *dirh );
LONG (*closedir)( DIR *dirh );
LONG (*pathconf)( fcookie *dir, WORD which );
LONG (*dfree)( fcookie *dir, long *buf );
LONG (*writelabel)( fcookie *dir, char *name );
LONG (*readlabel)( fcookie *dir, char *name );
LONG (*symlink)( fcookie *dir, char *name, char *to );
LONG (*readlink)( fcookie *file, char *buf, short buflen );
LONG (*hardlink)( fcookie *fromdir, char *fromname,
fcookie *todir, char *toname );
LONG (*fscntl)( fcookie *dir, char *name, WORD cmd, LONG arg );
LONG (*dskchng)( WORD dev );
LONG zero;
} FILESYS;
The members of the FILESYS structure are interpreted by MiNT as follows:
Member Meaning
next This member is a pointer to the next FILESYS structure in the
kernel's linked list. It should be left as NULL.
fsflags This is a bit mask of flags which define attributes of the
file system as follows:
Name Mask Meaning
FS_KNOPARSE 0x01 Kernel shouldn't do directory parsing
(common for networked file systems).
FS_CASESENSITIVE 0x02 File system names are case-sensitive
(common for Unix compatible file
systems).
FS_NOXBIT 0x04 Files capable of being read are capable
of being executed (present in most file
systems).
root This function is called by the kernel to retrieve a file
cookie for the root directory of the drive associated with
BIOS device dev. When initializing, the kernel will query each
file system, in turn, to determine which file system should
handle a particular drive. If your file system recognizes the
drive specified by dev it should fill in the fcookie structure
as appropriate and return E_OK. If the drive is not
compatible with your file system, return an appropriate
negative GEMDOS error code (usually EDRIVE).
lookup This function should translate a file name into a cookie. If
the FS_KNOPARSE bit of fsflags is not set, name will be the
name of a file in the directory specified by the fcookie dir.
If the FS_KNOPARSE bit was set, name will be a path name
relative to the specified directory dir. If the file is found,
the fcookie structure fc should be filled in with appropriate
details and either E_OK or EMOUNT (if name is '..' and dir
specifies the root directory) should be returned, otherwise an
appropriate error code (like EFILNF) should be returned.A
lookup() call with a NULL name or with a name of '.' should
always succeed and return a cookie representing the current
directory. When creating a file cookie, symbolic links should
never be followed.
creat This function is used by the kernel to instruct the file
system to create a file named name in the directory specified
by dir with attrib attributes (as defined by Fattrib()) and
mode permissions as follows (note that the values are in
octal and not is hexadecimal):
Name Mask Permission
S_IXOTH 0000001 Execute permission for all others.
S_IWOTH 0000002 Write permission for all others.
S_IROTH 0000004 Read permission for all others.
S_IXGRP 0000010 Execute permission for processes with same group ID.
S_IWGRP 0000020 Write permission for processes with same group ID.
S_IRGRP 0000040 Read permission for processes with same group ID.
S_IXUSR 0000100 Execute permission for processes with same user ID.
S_IWUSR 0000200 Write permission for processes with same user ID.
S_IRUSR 0000400 Read permission for processes with same user ID.
S_ISVTX 0001000 Sticky bit
S_ISGID 0002000 Alter effective group ID when executing this file.
S_ISUID 0004000 Alter effective user ID when executing this file.
S_IFSOCK 0010000 File is a FreeMiNTNet socket file.
S_IFCHR 0020000 File is a BIOS (character) special file.
S_IFDIR 0040000 File is a directory.
S_IFBLK 0060000 File is a block special file.
S_IFREG 0100000 File is a regular file.
S_IFIFO 0120000 File is a FIFO (named pipe).
S_IMEM 0140000 File is a memory region.
S_IFLNK 0160000 File is a symbolic link.
If the file is created successfully, the fcookie structure fc
should be filled in to represent the newly created file and E_OK should be returned. On an error, an appropriate GEMDOS error
code should be returned.
getdev This function is used by the kernel to identify the device
driver that should be used to do file I/O on the file named by
fc. The function should return a pointer to the device driver
and place a user-defined value in the longword pointed to by
devspecial. If the function fails, the function should return
and place a negative GEMDOS error code in the longword pointed
to by devspecial.
getxattr This function should fill in the XATTR structure pointed to by
xattr with the extended attributes of file fc. If the function
succeeds, the routine should return E_OK, otherwise a negative
GEMDOS error code should be returned.
chattr This function is called by the kernel to instruct the file
system to change the attributes of file fc to those in attr
(with only the low eight bits being signifigant). The function
should return a standard GEMDOS error code on exit.
chown This function is called by the kernel to instruct the file
system to change the file fc's group and user ownership to gid
and uid respectively. The kernel checks access permissions prior to calling this function so the file system does not
have to.
chmode This function is called by the kernel to instruct the file
system to change the access permissions of file fc to those in
mode. The mode parameter passed to this function will never
contain anything but access permission information (i.e. no
file type information will be contained in mode). The call
should return a standard GEMDOS error code on exit.
mkdir This function should create a new subdirectory called name in
directory dir with access permissions of mode. The file system
should ensure that directories such as '.' and '..' are
created and that a standard GEMDOS error code is returned.
rmdir This function should remove the directory whose name is name
and whose cookie is pointed to by dir. This call should allow
the removal of symbolic links to directories and return
a standard GEMDOS error code.
remove This function should delete the file named name that resides
in directory dir. If more than one 'hard' link to this file
exists, then only this link should be destroyed and the file
contents should be left untouched. Symbolic links to file fc,
however, should be removed. This function should not allow the
deletion of directories and should return with a standard
GEMDOS error code.
getname This function should fill in the buffer pointed to by pathname
with as many as PATH_MAX (128) characters of the path name of
directory dir expressed relatively to directory relto. If
relto and dir point to the same directory, a NULL string
should be returned. For example, if relto points to directory
"\FOO" and dir points to directory "\FOO\BAR\SUB" then
pathname should be filled in with "\BAR\SUB".
rename This function should rename the file oldname which resides in
directory olddir to the new name newname which resides in
newdir. The file system may choose to support or not support
cross-directory renames. The function should return a standard
GEMDOS error code. If no renames at all are supported then
EINVFN should be returned.
opendir This function opens directory dirh for reading. The parameter
tosflag is a copy of the flags member of the DIR structure as
defined below:
typedef struct dirstruct
{
fcookie fc; /* Directory cookie */
UWORD index; /* Index of current entry */
UWORD flags; /* TOS_SEARCH (1) or 0 */
char fsstuff[60]; /* File system dependent */
} DIR;
If tosflags (dirstruct.flags) is contains the mask TOS_SEARCH
the file system is responsible for parsing the names into
something readable by TOS domain applications. The file system
should initialize the index and fsstuff members of dirh and
return an appropriate GEMDOS error code.
readdir This function should read the next filename from directory
dirh. The fcookie structure fc should be filled in with the
details of this file. If dirh->flags does not contain the mask
TOS_SEARCH then the filename should be copied into the buffer
pointed to by name. If dirh->flags does contain the mask
TOS_SEARCH then the first four bytes of name should be treated
as a longword and filled in with an index value uniquely
identifying the file and the filename should be copied
starting at &name[4]. In either case, if the filename is longer
than namelen, rather than filling in the buffer name, the
function should return with ENAMETOOLONG. If this is the last
file in the directory, ENMFIL should be returned, otherwise
return E_OK.
rewinddir This function should reset the members of dirh so that any
internal pointers point at the first file of directory dirh.
This function should return a standard GEMDOS error code.
closedir This function should clear any allocated memory and clean up
any structures used by the search on dirh. This function
should return a standard GEMDOS error code.
pathconf This function should return information about the directory
dir based on mode mode. For mode values and return values, see
Dpathconf().
dfree This function should return free space information about the
drive directory dir is located on. The format of the buffer
pointed to by buf is the same as is used by Dfree(). This
function should return a standard GEMDOS error code.
writelabel This function is used to change the volume name of a drive
which contains the directory dir. The new name name should be
used to write (or rename the volume label). If the write is
actually an attempt to rename the label and the file system
does not support this function then EACCDN should be returned.
If the file system does not support the concept of volume
labels then EINVFN should be returned. Otherwise, a return
value of E_OK is appropriate.
readlabel This function should copy the volume label name of the drive
on which directory dir is contained in the buffer name. If
namelen is less than the size of the volume name, ENAMETOOLONG should be returned. If the concept of volume names is not
supported by the file system, EINVFN should be returned. If no
volume name was ever created, EFILNF should be returned. Upon
successful error of the call, E_OK should be returned.
symlink This function should create a symbolic link in directory dir
named name. The symbolic link should contain the NULL
terminated string in to. If the file system does not support
symbolic links it should return EINVFN, otherwise a standard
GEMDOS error code should be returned.
readlink This function should copy the contents of symbolic link file
into buffer buf. If the length of the contents of the symbolic
link is greater than buflen, ENAMETOOLONG should be returned.
If the file system does not support symbolic links, EINVFN should be returned. In all other cases, a standard GEMDOS error code should be returned.
hardlink This function should create a 'hard' link called toname
residing in todir from the file named fromname residing in
fromdir. If the file system does not support hard links,
EINVFN should be returned. Otherwise, a standard GEMDOS error
code should be returned.
fscntl This function performs a file system specific function on
a file whose name is name that resides in directory dir. The
cmd and arg functions parallel those of Dcntl(). In most
cases, this function should simply return EINVFN. If your file
system wishes to expose special features to the user through
Dcntrl() then your file system should handle them here as it
sees fit.
dskchng This function is used by the kernel to confirm a 'media
change' state reported by Mediach(). If the file system agrees
that a media change has taken place, it should invalidate any
appropriate buffers, free any allocated memory associated with
the device, and return 1. The kernel will then invalidate any
open files and relog the drive with the root() functions of
each installed file system. If a media change has not taken
place, simply return a value of 0.
zero This member is reserved for future expansion and must be set
to 0L.