This file documents the libhfs.a library for accessing HFS volumes.
Copyright (C) 1996-1998 Robert Leslie

$Id: libhfs.txt,v 1.11 1998/11/02 22:08:47 rob Exp $

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

Exported Data

  const 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).

    This string is encoded using ISO 8859-1.

    In all cases when an error occurs, the global variable `errno' is also
    set to an appropriate value.

  unsigned char hfs_charorder[];

    This array contains the relative sorting order of characters in HFS
    filenames according to the semantics of the Macintosh character set
    and the MacOS string comparison routines as used by HFS. The array can
    be indexed by unsigned character quantities; the resulting value can be
    compared to other array values to determine the relative sorting order
    of the corresponding character indices.

Public Routines

  ----- Volume Routines -----

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

    This routine attempts to open an HFS volume from a source pathname. The
    given `pnum' indicates which ordinal HFS partition is to be mounted,
    or can be 0 to indicate the entire medium should be mounted (ignoring
    any partition structure). If this value is not 0, the requested
    partition must exist.

    The `flags' argument specifies how the volume should be mounted.
    HFS_MODE_RDONLY means the volume should be mounted read-only.
    HFS_MODE_RDWR means the volume must be opened read/write. HFS_MODE_ANY
    means the volume can be mounted either read-only or read/write, with
    preference for the latter.

    The `flags' argument may also specify volume options. HFS_OPT_NOCACHE
    means not to perform any internal block caching, such as would be
    unnecessary for a volume residing in RAM, or if the associated overhead
    is not desired. HFS_OPT_ZERO means that newly-allocated blocks should be
    zero-initialized before use, primarily as a security feature for systems
    on which blocks may otherwise contain random data. Neither of these
    options should normally be necessary, and both may affect performance.

    If an error occurs, this function returns NULL. Otherwise 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.

  int hfs_flush(hfsvol *vol);

    This routine causes all pending changes to be flushed to an HFS volume.
    If a volume is kept open for a long period of time, it would be wise
    to call this periodically to avoid corrupting the volume due to
    unforeseen circumstances (power failure, floppy eject, etc.)

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

  void hfs_flushall(void);

    This routine is similar to hfs_flush() except that all mounted volumes
    are flushed, and errors are not reported.

  int hfs_umount(hfsvol *vol);

    The specified HFS volume is unmounted; all open files and directories
    on the volume are closed, all pending changes to the volume are
    flushed, and all memory allocated for the volume is freed.

    All volumes opened with hfs_mount() must eventually be closed with
    hfs_umount(), or they will risk corruption.

    If an error occurs, this function returns -1. Otherwise it returns 0.
    In either case, the volume structure pointer will become invalid, as
    will all pointers to open file or directory structures associated with
    the volume.

  void hfs_umountall(void);

    This routine is similar to hfs_umount() except that all mounted volumes
    are closed, and errors are not reported.

    This routine may be useful to call just before a process terminates to
    make sure any remaining open volumes are properly closed.

  hfsvol *hfs_getvol(const char *name);

    This routines searches all mounted volumes for one having the given
    `name', and returns its volume structure pointer. If more than one
    volume have the same name, the most recently mounted one is returned. If
    no volume matches the given name, a NULL pointer is returned.

    The given `name' is assumed to be encoded using MacOS Standard Roman.

    If a NULL pointer is passed to this routine, the current volume is
    returned, if any.

  void hfs_setvol(hfsvol *vol);

    The routine changes the "current" volume. Most HFS routines will accept
    a NULL volume pointer to mean the current volume; by default, the
    current volume is the last one which was mounted.

  int hfs_vstat(hfsvol *vol, hfsvolent *ent);

    This routine fills the volume entity structure `*ent' with information
    about a mounted volume. The fields of the structure are defined in
    the hfs.h header file.

    This routine returns 0 unless a NULL pointer is passed for the volume
    and no volume is current, in which case it returns -1.

  int hfs_vsetattr(hfsvol *vol, hfsvolent *ent);

    This routine allows some attributes of a volume to be changed. The
    attributes which may be changed are: ent->clumpsz, ent->crdate,
    ent->mddate, ent->bkdate, and ent->blessed. Note that the default file
    clump size may only be changed to be a multiple of the volume's
    allocation block size, and the "blessed" folder must either be 0 or a
    valid folder CNID.

    To change the volume's name, use hfs_rename().

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

  ----- Directory Routines -----

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

    The "current working directory" for the given volume is changed.
    `path' can be either a relative or absolute HFS path.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

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

  long hfs_getcwd(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_setcwd() or hfs_dirinfo().

  int hfs_setcwd(hfsvol *vol, long id);

    This routine changes the current working directory for the given
    volume. A directory must exist with the given id.

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

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

    This function looks up the given directory ID `*id' and stores in its
    place the 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 HFS_MAX_FLEN + 1 (32) bytes long.

    The string `name' will be encoded using MacOS Standard Roman.

    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 a directory ID of HFS_CNID_ROOTDIR, and a pseudo-parent ID
    of HFS_CNID_ROOTPAR.

  hfsdir *hfs_opendir(hfsvol *vol, const 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. As a special case, if `path' is an empty string, a
    "meta-directory" will be opened containing the root directories from
    all of the currently mounted volumes.

    The string `path' is assumed to be encoded using MacOS Standard Roman.

    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 routine fills the directory entity structure `*ent' with
    information about the next item in the given open directory. The
    fields of the structure are defined in the hfs.h header file.

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

    When no more items occur in the directory, this function returns -1
    and sets `errno' to ENOENT.

  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.
    In either case, the directory structure pointer will no longer be valid.

  ----- File Routines -----

  hfsfile *hfs_create(hfsvol *vol, const char *path,
                      const char *type, const char *creator);

    This routine creates a new, empty file with the given path, type, and
    creator. The type and creator must be strings of length 4, and have
    particular meaning under MacOS.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

    If the creation is successful, the file is opened and a pointer to a
    file structure is returned, the same as if hfs_open() had been called.

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

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

    This function opens an HFS file in preparation for I/O. Both forks of
    the file may be manipulated once the file is opened; hfs_setfork() is
    used to select the current fork. By default, the data fork is current.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

    A pointer to a file structure is returned. This pointer should be
    passed to other routines to manipulate the file.

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

  int hfs_setfork(hfsfile *file, int fork);

    This routine selects the current fork in an open file for I/O. HFS
    files have two forks, data and resource. Resource forks normally contain
    structured data, although these HFS routines make no distinction
    between forks when reading or writing. It is up to higher-level
    applications to make sense of the information read or written from
    either fork.

    If 0 is passed to this routine, the data fork is selected. Otherwise
    the resource fork is selected. The seek pointer for the file is
    automatically reset to the beginning of the newly selected fork.

    As a side effect, this routine causes any excess disk blocks allocated
    for the fork which was current before the call to be freed; normally
    extra blocks are allocated during file writes to promote contiguity.
    This routine will return -1 if an error occurs in this process;
    otherwise it will return 0. The current fork will have been changed
    regardless.

  int hfs_getfork(hfsfile *file);

    This routine returns an indication of which fork is currently active
    for I/O operations on the given file. If 0 is returned, the data fork
    is selected. Otherwise the resource fork is selected.

  long hfs_read(hfsfile *file, void *ptr, unsigned long len);

    This routine reads up to `len' bytes from the current fork of an HFS
    file and places them into the buffer pointed to by `ptr' (which must be
    at least `len' bytes long.) The number of bytes actually read is
    returned, and may be less than `len' if the end of the file is reached.

    If this routine returns 0, there is no more data to be read from the
    file. If an error occurs, this routine will return -1.

    It is most efficient to read data in multiples of HFS_BLOCKSZ byte
    blocks at a time.

  long hfs_write(hfsfile *file, const void *ptr, unsigned long len);

    This routine writes up to `len' bytes of data to the current fork of an
    HFS file from the buffer pointed to by `ptr'. The number of bytes
    actually written is returned. If an error occurs, this routine will
    return -1.

    If the end of the file is reached before all bytes have been written,
    the file is automatically extended.

    It is most efficient to write data in multiples of HFS_BLOCKSZ byte
    blocks at a time.

  int hfs_truncate(hfsfile *file, unsigned long len);

    This routine causes the current fork of the specified open file to be
    truncated to at most `len' bytes.

    The disk blocks associated with the freed portion of the file are not
    actually deallocated until either the current fork is changed or the
    file is closed.

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

  long hfs_seek(hfsfile *file, long offset, int from);

    This routine changes the current seek pointer for the specified open
    file. This pointer determines where the next call to hfs_read() or
    hfs_write() will read or write data within the current fork.

    If `from' is HFS_SEEK_SET, the pointer is set to the absolute position
    given by `offset'.

    If `from' is HFS_SEEK_CUR, the pointer is offset from its current
    position by the amount `offset'. Positive offsets seek forward; negative
    offsets seek backward.

    If `from' is HFS_SEEK_END, the pointer is offset from the end of the
    file by the amount `offset', which ought not be positive.

    It is not presently possible to set the seek pointer beyond the logical
    end of the file.

    The new absolute position of the seek pointer is returned, unless an
    invalid argument was specified, in which case -1 is returned.

  int hfs_close(hfsfile *file);

    This routine causes all pending changes to the specified file to be
    flushed, and all storage associated with the file structure to be
    freed. Any excess disk blocks associated with the file are also
    deallocated at this time.

    If an error occurs, this routine returns -1. Otherwise it returns 0.
    In either case, the file structure pointer will no longer be valid.

  ----- Catalog Routines -----

  int hfs_stat(hfsvol *vol, const char *path, hfsdirent *ent);

    This routine fills the directory entity structure `*ent' with
    information about the file or directory specified by `path' on the
    given volume. The fields of the structure are defined in the hfs.h
    header file.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

    If there is no such path, or if another error occurs, this routine
    returns -1. Otherwise it returns 0.

  int hfs_fstat(hfsfile *file, hfsdirent *ent);

    This routine is similar to hfs_stat() except it returns information
    about a file that is already open.

    If an error occurs, this routine returns -1. Otherwise it returns 0.

  int hfs_setattr(hfsvol *vol, const char *path, const hfsdirent *ent);

    This routine changes various attributes of an existing file or
    directory. The attributes which may be changed are: ent->crdate,
    ent->mddate, ent->bkdate, ent->fdflags, ent->fdlocation,
    ent->u.file.type, ent->u.file.creator, and ent->u.dir.rect. Also, the
    locked status of a file may be changed with ent->flags & HFS_ISLOCKED.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

    If an error occurs, this routine returns -1. Otherwise it returns 0.

  int hfs_fsetattr(hfsfile *file, const hfsdirent *ent);

    This routine is similar to hfs_setattr() except it manipulates a file
    that is already open.

    If an error occurs, this routine returns -1. Otherwise it returns 0.

  int hfs_mkdir(hfsvol *vol, const char *path);

    This routine creates a new, empty directory with the given path.
    All parent directories must already exist, but there must not already
    be a file or directory with the complete given path.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

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

  int hfs_rmdir(hfsvol *vol, const char *path);

    This routine deletes the directory with the given path. The directory
    must be empty.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

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

  int hfs_delete(hfsvol *vol, const char *path);

    This routine deletes both forks of the file with the given path.

    The given `path' is assumed to be encoded using MacOS Standard Roman.

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

  int hfs_rename(hfsvol *vol, const char *srcpath, const char *dstpath);

    This routine moves and/or renames the given `srcpath' to `dstpath'.
    The source must exist; the destination must not exist, unless it is a
    directory, in which case an attempt will be made to move the source
    into the destination directory without changing its name.

    If both `srcpath' and `dstpath' refer to root directories, the volume
    specified by `srcpath' will be renamed. Note that volume names may
    only have 1-27 (HFS_MAX_VLEN) characters, while all other names may
    have 1-31 (HFS_MAX_FLEN) characters.

    The given `srcpath' and `dstpath' are assumed to be encoded using MacOS
    Standard Roman.

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

  ----- Media Routines -----

  int hfs_zero(const char *path, unsigned int maxparts,
               unsigned long *blocks);

    This routine initializes a medium with a new, empty driver descriptor
    record and partition map. This is only necessary if it is desired to
    partition the medium; the medium can be used as a whole without
    partitions by specifying 0 to the routines which require a partition
    number.

    The partition map will be empty, with the exception of an entry for the
    partition map itself, plus an entry for the rest of the medium as free
    space. To be useful, one or more HFS partitions should be created with
    hfs_mkpart().

    The partition map will be created just large enough to allow `maxparts'
    individual partitions to be created, not counting the partitions created
    automatically by this routine. This number should be conservative, as
    it may be impossible to create more than this many partitions for the
    lifetime of the medium without re-initializing.

    If `blocks' is not NULL, the total number of blocks available for
    partitioning (after the partition map structures have been created) will
    be stored at this location.

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

  int hfs_mkpart(const char *path, unsigned long len);

    This routine creates a new HFS partition having `len' blocks on the
    given medium. Space for the partition will be taken from the available
    free space as indicated in the existing partition map.

    It may not be possible to create the requested partition if there are
    not enough free contiguous blocks on the medium, or if there is only
    one slot left in the partition map and the request does not specify
    all the remaining blocks in the free space. (The partition map cannot
    leave any blocks in the medium unaccounted for.)

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

  int hfs_nparts(const char *path);

    This routine determines the number of HFS partitions present on the
    given medium, if any. If the medium specified by `path' is not
    partitioned, -1 will be returned. Otherwise, a number denoting the total
    number of HFS partitions is returned, including (possibly) 0.

    The number returned by this routine can help determine if a particular
    medium is partitioned, and if so, the allowable range of partition
    numbers which can be passed to the routines which require one. However,
    passing 0 as a partition number always refers to the entire medium,
    ignoring all partitions.

    If an error occurs, this function returns -1.

  int hfs_format(const char *path, int pnum, int mode, const char *vname,
                 int nbadblocks, const unsigned long badblocks[]);

    This routine writes a new HFS file system to the specified `path', which
    should be a block device or a writable file. The size of the volume is
    determined either by the maximum size of the device or size of the file,
    or by the size of the indicated partition within the medium.

    If `pnum' is > 0, it selects an ordinal HFS partition in the device
    to receive the file system. 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.

    Volume options may be specified in the `mode' argument. In addition to
    the options accepted by hfs_mount(), HFS_OPT_2048 may be specified to
    request that the volume allocation blocks be aligned on physical
    2048-byte block boundaries. Such a constraint is necessary to support
    some hybrid CD-ROM file system formats, but is otherwise unnecessary and
    may result in fewer allocation blocks altogether.

    The volume is given the name `vname', which must be between 1 and
    HFS_MAX_VLEN (27) characters in length inclusively, and cannot contain
    any colons (':'). This string is assumed to be encoded using MacOS
    Standard Roman.

    It is possible to map out or "spare" bad blocks on the device such that
    the file system will be made aware of these blocks and will not attempt
    to use them to store data. To perform this magic, hfs_format() may be
    passed an array of block numbers to spare. These numbers must
    correspond to logical 512-byte blocks on the device and should be
    relative to the beginning of the volume's partition, if any. If no
    blocks need to be spared, 0 should be passed for `nbadblocks', and
    `badblocks' may be a NULL pointer. Note that an error can occur if a
    bad block occurs in a critical disk structure, or if there are too
    many bad blocks (more than 25%) in the volume.

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

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