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.

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