
This file documents the libhfs.a library for accessing HFS volumes.

===============================================================================

Exported data

  char *hfs_error;

    This contains a pointer to a C string describing the last HFS error.
    It is generally only valid after an HFS routine has returned an error
    code (-1 or a NULL pointer).

Public routines

  hfsvol *hfs_mount(char *path, int pnum);

    This routine attempts to open an HFS volume from a UNIX source
    pathname. If the source medium is partitioned, `pnum' indicates
    which cardinal HFS partition should be mounted, and is usually 1.

    An attempt is made to open the volume read/write; if this fails,
    the volume will be considered to be read-only.

    A pointer to a volume structure is returned. This pointer is used
    to access the volume and must eventually be passed to hfs_umount()
    to flush and close the volume and free all associated memory.

  char *hfs_vname(hfsvol *vol);

    This routine returns a pointer to a string containing the given
    volume's name. This string is stored in a static area that must
    not be altered.

  unsigned long hfs_freebytes(hfsvol *vol);

    This routine returns the number of free bytes on the given volume.

  long hfs_vcrdate(hfsvol *vol);

    This routine returns the date of the given volume's creation, in
    the same format as returned by time(2).

  long hfs_vmddate(hfsvol *vol);

    This routine returns the date of the given volume's last modification,
    in the same format as returned by time(2).

  int hfs_format(char *path, int pnum, char *vname)

    This routine writes a new HFS filesystem to the specified device or
    file pathname. The size of the volume is determined either by the
    maximum size of the device or the size of the existing file.

    If `pnum' is > 0, it selects an ordinal HFS partition in the device
    to receive the filesystem. The partition must already exist; an error
    will result if it cannot be found. With `pnum' == 0, any partition
    structure on the existing medium will be ignored, and the entire
    device will be used for the new HFS volume.

    The volume is given the name `vname', which must be between 1 and 27
    characters in length inclusively, and cannot contain any colons (':').

    If an error occurs, this function returns -1, otherwise it returns 0.

  int hfs_chdir(hfsvol *vol, char *path);

    The "current working directory" for the given volume is changed.
    `path' can be either a relative or absolute HFS path. If an error
    occurs, -1 is returned; otherwise 0 is returned.

  long hfs_cwdid(hfsvol *vol);

    The internal directory ID of the current working directory for the
    given volume is returned. This value is typically only useful for
    passing to hfs_dirinfo().

  int hfs_dirinfo(hfsvol *vol, long *id, char *name);

    This function looks up the given directory ID `*id' and stores in its
    place and directory ID of its parent. If `name' is not NULL, the name
    of the (child) directory is also stored in the buffer pointed to by it,
    which must be at least 32 characters long.

    If an error occurs, this function returns -1, otherwise it returns 0.

    This function can be called repeatedly to construct a full pathname
    to the current working directory. The root directory of a volume
    always has directory ID of 2, and a pseudo-parent ID of 1.

  hfsdir *hfs_opendir(hfsvol *vol, char *path);

    This function prepares to read the contents of a directory. `path'
    must be either an absolute or relative pathname to the desired HFS
    directory.

    This function returns a pointer which must be passed to the other
    directory-related routines to read the directory.

    If an error occurs, this function returns a NULL pointer.

  int hfs_readdir(hfsdir *dir, hfsdirent *ent);

    This function reads the next item from the open directory and fills
    in an hfsdirent structure pointed to by `ent'.

    If an error occurs, this function returns -1, otherwise it returns 0.

  int hfs_closedir(hfsdir *dir);

    This function closes an open directory and frees all associated
    memory.

    If an error occurs, this function returns -1, otherwise it returns 0.

  hfsfile *hfs_open(hfsvol *vol, char *path);

    This function opens an HFS file in preparation for I/O.

