NAME
hfssh - Tcl interpreter with HFS extensions
SYNOPSIS
hfssh [script]
DESCRIPTION
hfssh is a Tcl interpreter like tclsh(1) but which also implements the
following extensions to support manipulation of Macintosh HFS media:
hfs mount path [partno]
Mounts the indicated HFS partition from the given path. An HFS
volume handle is returned, which may be used for further volume
commands described below.
hfs zero path nparts
The given path is overwritten with a Macintosh partition
structure which can accommodate up to nparts partitions. All
space on the medium is initially allocated to an empty
partition, from which new partitions can be created using hfs
mkpart. The number of blocks in this empty space available for
partitioning is returned.
hfs mkpart path nblocks
A new HFS partition is created from the available free space on
the specified Macintosh-partitioned medium. The partition is
created with a size of nblocks. Any remaining free blocks left
in the empty partition space can be further allocated to other
new partitions, as long as there are enough partition slots
remaining.
N.B. When the last remaining partition slot is used, all
remaining free space must be allocated to it. It is therefore
best to consider this when initially creating the total number
of partition slots with hfs zero.
hfs nparts path
This command returns the number of HFS partitions which exist on
the Macintosh-formatted medium specified by path. If path does
not appear to have a Macintosh partition map, or if an error
occurs, this command will return -1. Otherwise, it will return a
number greater than or equal to 0.
hfs format path partno vname [bblist]
This command creates a new HFS volume by formatting the given
path and partition partno and giving it a volume label vname.
If it is desired to "spare" some blocks from being used by the
volume, a list of "bad block" numbers can be given, relative to
the beginning of the partition. The given blocks will be mapped
out of use (if possible) and the size of the resulting volume
will be decreased.
hfs flushall
All pending changes to all open volumes are flushed immediately.
This is useful to do periodically to avoid accidental loss of
data when volumes are open for long periods of time.
hfs chartrans fromset toset string
This command translates the given string from the fromset
character set to the toset set. Both fromset and toset can be
one of latin1 (ISO 8859-1) or macroman (MacOS Standard Roman).
A new (translated) string is returned.
The translation is not necessarily reversible, since the two
character sets do not have a complete one-to-one mapping.
hfs version
The current running version of hfsutils is returned.
hfs copyright
A copyright notice is returned.
hfs author
The name and email address of the author of hfsutils is
returned.
hfs license
A license statement for hfsutils is returned.
vol vname
The volume name of the given vol handle is returned. This is
also the name of the volume’s root directory, needed to
construct absolute pathnames on the volume.
vol size
A list of two numbers is returned; the first is the total size
of the given vol (in bytes), and the second is the number of
free bytes that are currently available.
vol crdate
The creation date of the given vol is returned, expressed as a
number of seconds since 00:00:00 01-Jan-1970 UTC.
vol mddate
The last modification date of the given vol is returned,
expressed as a number of seconds since 00:00:00 01-Jan-1970 UTC.
vol islocked
A boolean value (either 1 or 0) is returned, indicating whether
the given vol handle is locked for read-only access. It may be
locked because the medium is physically locked through hardware,
or because the medium was opened read-only for special reasons
(such as another process also has the medium open).
vol umount
The indicated vol is unmounted, flushing any unsaved data to the
volume and closing the access path to the medium. The vol handle
subsequently becomes invalid for further use.
vol cwd
A numeric value is returned indicating the catalog node ID
(CNID) of the current working directory on the given vol. This
value can be passed to vol dirinfo to learn the directory’s name
and parent CNID.
vol path
A list of directory names is returned, representing the
hierarchy between the root and the current directory. These
names can be joined with vol sepchar characters (:) to construct
an absolute pathname to the current directory.
The same information can be acquired by traversing the CNIDs
from the current directory to the root using vol dirinfo. (The
root directory always has a CNID of 2.)
vol dir [path]
A list is returned describing the contents of the given
directory path (defaulting to the current directory) on the
given vol. Each element of the list describes one entry, and
contains a set of attribute/value pairs represented as another
list, suitable for assignment to a Tcl array using array set.
vol flush
All pending changes to the given volume are flushed immediately.
vol sepchar
The HFS path separator character ":" is returned.
vol cd path
vol chdir path
The current working directory on the given volume is changed to
path, which may be either an absolute or relative path.
vol dirinfo cnid
A two-element list describing the directory having the given
cnid on the given vol is returned. The first element contains
the name of the directory, while the second element contains the
CNID of the directory’s parent. Two CNID values are special: the
root directory of the volume has CNID 2, and the "parent" of the
root directory is returned with CNID 1.
vol open path
The file on vol having the given path is opened. An HFS file
handle is returned, which may be used for further file commands
described below.
vol stat path
Information about the file or directory having the given path is
returned in much the same way as vol dir except that only the
single argument is described (not its contents).
vol mkdir path
A new directory on vol having the given path is created. All of
the parent directories leading to path must already exist, but
path itself must not.
vol rmdir path
The directory on vol with the given path is removed. The
directory must be empty.
vol delete path
The file on vol with the given path is removed. Both resource
and data forks of the file are deleted.
vol touch path
The modification time for the file or directory specified by
path on the given vol is updated to the current time.
vol glob pattern
The given pattern is treated as a list of globbing patterns,
each of which may be expanded to the names of files or
directories on the given vol according to the globbing rules
described in the hfsutils(1) documentation. The resulting
pathnames are returned in a (possibly longer) list. If a pattern
does not match any file or directory name, it is returned in the
resulting list unchanged.
vol bless path
The folder named by the given path is "blessed" as the MacOS
System Folder. For this to be useful, the folder should contain
valid Macintosh System and Finder files.
vol rename oldpath newpath
The existing oldpath on the given vol is renamed to newpath,
possibly changing its location at the same time. If newpath
already exists, it must be a directory, and the item will simply
be moved into it keeping the same name. (In the latter case,
there must not be another file or directory already with the
same name; in no case will another file or directory be
overwritten.)
vol create path type creator
A new, empty file is created on vol having the given path, and
an HFS file handle is returned in the same manner as vol open.
The file is given the specified MacOS type and creator codes,
which must be 4 character strings.
vol copy srcpath dstvol dstpath
The given file srcpath located on vol is copied to dstpath
located on dstvol (which may be the same as vol). The file and
its attributes are copied verbatim; no translation is performed.
vol copyin mode srcpath dstpath
The specified local (UNIX) srcpath is copied into the given vol
as a file having the specified (HFS) dstpath. A translation
mode must be given as one of macbinary, binhex, text, or raw.
vol copyout mode srcpath dstpath
The specified (HFS) srcpath on the given vol is copied out as a
local file having the specified (UNIX) dstpath. A translation
mode must be given as one of macbinary, binhex, text, or raw.
file close
The indicated file is closed, all pending changes to the file
are flushed, and the file handle becomes invalid for any
subsequent operation.
file tell
A numeric index is returned indicating the character position
within file at which the next read or write operation will
occur.
file stat
Information about the given file is returned in much the same
way as vol stat.
file getfork
If the given file is currently performing I/O on its data fork,
the string "data" is returned. Otherwise, the string "rsrc" is
returned. When files are opened, they will default to read/write
on their data fork. The current fork may be changed with file
setfork.
file setfork fork
The current fork of the given file is set to fork (which must be
one of data or rsrc), and the current read/write position is
reset to the beginning of the file.
file seek pos [from]
The character position for the next read or write on file is
changed to pos, relative to the indicated from position, which
must be one of start, current, or end. The default is to
position relative to the start of the file.
file read length
length bytes are read from the current read/write position in
file, and these bytes are returned as a string. This string may
be shorter than length in some circumstances, or may even be
empty, indicating the end of the file has been reached.
file write string
The given string is written to file at the current read/write
position. The number of bytes actually written to the file is
returned, and may be less than the length of the string in
unusual circumstances (such as when the volume is full).
SEE ALSO
hfsutils(1), hfs(1), tclsh(1)
NOTES
Precautions are taken to ensure all open files and mounted volumes are
cleanly closed and unmounted before exiting the shell, however abnormal
termination (e.g. CTRL-C) can circumvent this, potentially leaving
volumes in an inconsistent state. Judicious use of hfs flushall may
help reduce this risk.
BUGS
Tcl does not provide a mechanism for manipulating arbitrary binary
data. Therefore caution should be used when reading or writing files
containing anything other than plain text.
AUTHOR
Robert Leslie <rob@mars.org>