[Pancutan-commits] r56 - hfsbootfiles
tincho-guest at alioth.debian.org
tincho-guest at alioth.debian.org
Mon Aug 13 07:15:06 UTC 2007
Author: tincho-guest
Date: 2007-08-13 07:15:06 +0000 (Mon, 13 Aug 2007)
New Revision: 56
Added:
hfsbootfiles/libhfs.txt
Log:
Documentation forn libhfs from hfsutils
Added: hfsbootfiles/libhfs.txt
===================================================================
--- hfsbootfiles/libhfs.txt (rev 0)
+++ hfsbootfiles/libhfs.txt 2007-08-13 07:15:06 UTC (rev 56)
@@ -0,0 +1,517 @@
+
+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.
+
+===============================================================================
+
More information about the Pancutan-commits
mailing list