Celestin Apprentice 5/Apprentice-Release5.iso/Source Code/Libraries/CW GUSI 1.6.4/doc/pod/GUSI_Files.pod

Text File | 1995-04-07 | 9.9 KB | 338 lines | [TEXT/CWIE]

=head1 File system calls

Files are unlike sockets in many respects: Their length is
never changed by other processes, they can be rewound. There are also many calls which
are specific to files.

=head2 Differences to generic behavior


The following calls make no sense for files and return an error of C<EOPNOTSUPP>:

    socket()
    bind()
    listen()
    accept()
    connect()
    getsockname()
    getpeername()
    getsockopt()
    setsockopt()

The following calls I<will> work, but might be frowned upon by your friends
(besides, UNIX systems generally wouldn't like them):

    recv()
    recvfrom()
    recvmsg()
    send()
    sendto()
    sendmsg()

C<choose()> returns zero terminated C strings in C<name>.
It accepts an additional flag C<CHOOSE_DIR>. If this is set, C<choose()>
will select directories instead of files.

You may restrict the files presented for choosing by passing a pointer to
the following structure for the C<constraint> argument:

    typedef struct {
      short       numTypes;   /* Number of legitimate file types */
      SFTypeList  types;      /* The types, like 'TEXT' */
    } sa_constr_file;

C<select()> will give boring results. File descriptors are I<always> considered
ready to read or write, and I<never> give exceptions.

C<ioctl()> and C<fcntl()> don't support manipulating the blocking state of a file
descriptor or reading the number of bytes available for reading, but will accept
lots of other requests---Check with your trusty MPW C documentation.

=head2 Routines specific to the file system

In this section, you'll meet lots of good
old friends. Some of these routines also exist in the standard MPW libraries, but
the C<GUSI> versions have a few differences:

=over 4

=item *

File names are relative to the directory specified by chdir().

=item *

You can define special treatment for some file names (See below under
"Adding your own file families").

=item *

You can pass C<FSSpec> values to the routines by encoding
them with C<FSp2Encoding()> (See "FSSpec routines" below).

=back

C<int stat(const char * path, struct stat * buf)> returns information about a file.
C<struct stat> is defined as follows:

    struct stat   {
      dev_t    st_dev;     /* Volume reference number of file  */
      ino_t    st_ino;     /* File or directory ID             */
      u_short  st_mode;    /* Type and permission of file      */
      short    st_nlink;   /* Always 1             */
      short    st_uid;     /* Set to 0             */
      short    st_gid;     /* Set to 0             */
      dev_t    st_rdev;    /* Set to 0             */
      off_t    st_size;
      time_t   st_atime;   /* Set to st_mtime    */
      time_t   st_mtime;
      time_t   st_ctime;
      long     st_blksize;
      long     st_blocks;
    };

C<st_mode> is composed of a file type and of file permissions. The file type
may be one of the following:

=over 4

=item C<S_IFREG>

A regular file.

=item C<S_IFDIR>

A directory.

=item C<S_IFLNK>

A finder alias file.

=item C<S_IFCHR>

A console file under MPW or SIOW.

=item C<S_IFSOCK>

A file representing a UNIX domain socket.

=back

Permissions consist of an octal digit repeated three times. The three bits
in the digit have the following meaning:

=over 4

=item C<4>

File can be read.

=item C<2>

File can be written.

=item C<1>

File can be executed, i.e., its type is `APPL' or 'appe'. The definition of executability
can be customized with the C<GUSI_ExecHook> discussed in the advanced section.

=back

C<int lstat(const char * path, struct stat * buf)> works just like C<stat()>, but if C<path>
is a symbolic link, C<lstat()> will return information about the link and not about
the file it points to.

C<int fstat(int fd, struct stat * buf)> is the equivalent of C<stat()> for descriptors
representing open files. While it is legal to call C<fstat()> for sockets, the
information returned is not really interesting. The file type in C<st_mode> will be
C<S_IFSOCK> for sockets.

C<int chmod(const char * filename, mode_t mode)> changes the mode returned by C<stat()>. Currently,
the only thing you can do with C<chmod()> is to turn the write permission off an on. This
is translated to setting and clearing the file lock bit.

C<int utime(const char * file, const struct utimbuf * tim)> changes the modification time
of a file. C<struct utimbuf> is defined as:

    struct utimbuf {
      time_t actime;       /* Access time */
      time_t modtime;      /* Modification time */
    };

C<actime> is ignored, as the Macintosh doesn't store access times. The modification
of C<file> is set to C<modtime>.

C<int isatty(int fd)> returns C<1> if C<fd> represents a terminal (i.e. is connected
to C<"Dev:Stdin"> and the like), C<0> otherwise.

C<long lseek(int, long, int)> works the same as the C<MPW> routine, and will
return C<ESPIPE> if called for a socket.

C<int remove(const char *filename)> removes the named file. If C<filename> is a
symbolic link, the link will be removed and not the file.

C<int unlink(const char *filename)> is identical to C<remove()>. Note that
on the Mac, C<unlink()> on open files behaves differently from C<UNIX>.

C<int rename(const char *oldname, const char *newname)> renames and/or moves a
file. C<oldname> and C<newname> must specify the same volume, but as opposed to
the standard C<MPW> routine, they may specify different folders.

C<int open(const char*, int flags)> opens a named file. The C<flags> consist
of one of the following modes:

=over 4

=item C<O_RDONLY>

Open for reading only.

=item C<WR_ONLY>

Open for writing only.

=item C<O_RDWR>

Open for reading and writing.

=back

Optionally combined with one or more of:

=over 4

=item C<O_APPEND>

The file pointer is set to the end of the file before each write.

=item C<O_RSRC>

Open resource fork.

=item C<O_CREAT>

If the file does not exist, it is created.

=item C<O_EXCL>

In combination with C<O_CREAT>, return an error if file already exists.

=item C<O_TRUNC>

If the file exists, its length is truncated to 0; the mode is unchanged.

=item C<O_ALIAS>

If the named file is a symbolic link, open the link, not the file it points
to (This is most likely an incredibly bad idea).

=back

C<int creat(const char * name)> is identical to C<open(name, O_WRONLY+O_TRUNC+O_CREAT)>.
If the file didn't exist before, C<GUSI> determines its file type and creator of the
according to rules outlined in the section "Resources" below.

C<int faccess(const char *filename, unsigned int cmd, long *arg)> works the same
as the corresponding C<MPW> routine, but respects calls to C<chdir()> for partial
filenames.

C<void fgetfileinfo(char *filename, unsigned long *newcreator, unsigned long *newtype)>
returns the file type and creator of a file.

C<void fsetfileinfo(char *filename, unsigned long newcreator, unsigned long newtype)>
sets the file type and creator of a file to the given values.

C<int symlink(const char* linkto, const char* linkname)> creates a file named C<linkname> that
contains an alias resource pointing to C<linkto>. The created file should be
indistinguishible from an alias file created by the System 7 Finder. Note that
aliases bear only superficial similiarities to C<UNIX> symbolic links, especially
once you start renaming files.

C<int readlink(const char* path, char* buf, int bufsiz)> returns in C<buf> the name of the
file that C<path> points to.

C<int truncate(const char * path, off_t length)> causes a file to have a size equal to C<length>
bytes, shortening it or extending it with zero bytes as necessary.

C<int ftruncate(int fd, off_t length)> does the same thing with an open file.

C<int access(const char * path, int mode)> tests if you have the specified access
rights to a file. C<mode> may be either C<F_OK>, in which case the file is tested
for existence, or a combination of the following:

=over 4

=item C<R_OK>

Tests if file is readable.

=item C<W_OK>

Tests if file is writeable.

=item C<X_OK>

Tests if file is executable. As with C<stat()>, the definition of executability
may be customized.

=back

C<access()> returns 0 if the specified access rights exist, otherwise it sets
C<errno> and returns -1.

C<int mkdir(const char * path)> creates a new directory.

C<int rmdir(const char * path)> deletes an empty directory.

C<int chdir(const char * path)> makes all future partial pathnames relative to this
directory.

C<char * getcwd(const char * buf, int size)> returns a pointer to the current directory
pathname. If C<buf> is C<NULL>, C<size> bytes will be allocated using C<malloc()>.

Error codes:

=over 4

=item C<ENAMETOOLONG>

The pathname of the current directory is greater than C<size>.

=item C<ENOMEM>

C<buf> was C<NULL> and C<malloc()> failed.

=back

A number of calls facilitate scanning directories. Directory entries are represented by
following structure:

    struct dirent {
      u_long   d_fileno;      /* file number of entry */
      u_short  d_reclen;      /* length of this record */
      u_short  d_namlen;      /* length of string in d_name */
    #define MAXNAMLEN   255
      char  d_name[MAXNAMLEN + 1];  /* name must be no longer than this */
    };

C<DIR * opendir(const char * dirname)> opens a directory stream and returns a pointer or C<NULL>
if the call failed.

C<struct dirent * readdir(DIR * dirp)> returns the next entry from the directory or C<NULL>
if all entries have been processed.

C<long telldir(const DIR * dirp)> returns the position in the directory.

C<void seekdir(DIR * dirp, long loc)> changes the position.

C<void rewinddir(DIR * dirp)> restarts a scan at the beginning.

C<int closedir(DIR * dirp)> closes the directory stream.

C<int scandir(const char * path, struct dirent *** entries, int (*want)(struct dirent *), int (*sort)(const void *, const void *))>
scans a whole directory at once and returns
a possibly sorted list of entries. If C<want> is not C<NULL>, only entries for which C<want>
returns 1 are returned. If C<sort> is not C<NULL>, the list is sorted using C<qsort()> with
sort as a comparison function. If sort is C<NULL>, the list will be sorted alphabetically on
a Mac, but not necessarily on other machines.