.TH HFSSH 1 19-Feb-1998 HFSUTILS
.SH NAME
hfssh \- Tcl interpreter with HFS extensions
.SH SYNOPSIS
hfssh
.RI [ script ]
.SH DESCRIPTION
.B hfssh
is a Tcl interpreter like tclsh(1) but which also implements the following
extensions to support manipulation of Macintosh HFS media:
.PP
.TP
.BI "hfs mount" " path [partno]"
Mounts the indicated HFS partition from the given
.IR path .
An HFS volume handle is returned, which may be used for further volume
commands described below.
.TP
.BI "hfs zero" " path nparts"
The given
.I path
is overwritten with a Macintosh partition structure which can accommodate up to
.I nparts
partitions. All space on the medium is initially allocated to an empty
partition, from which new partitions can be created using
.BR "hfs mkpart" .
The number of blocks in this empty space available for partitioning is
returned.
.TP
.BI "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
.IR 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.
.IP
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
.BR "hfs zero" .
.TP
.BI "hfs nparts" " path"
This command returns the number of HFS partitions which exist on the
Macintosh-formatted medium specified by
.IR path .
If
.I 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.
.TP
.BI "hfs format" " path partno vname [bblist]"
This command creates a new HFS volume by formatting the given
.I path
and partition
.I partno
and giving it a volume label
.IR vname .
.IP
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.
.TP
.B "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.
.TP
.BI "hfs chartrans" " fromset toset string"
This command translates the given
.I string
from the
.I fromset
character set to the
.I toset
set. Both
.I fromset
and
.I toset
can be one of
.B latin1
(ISO 8859-1)
or
.B macroman
(MacOS Standard Roman).
A new (translated) string is returned.
.IP
The translation is not necessarily reversible, since the two character sets do
not have a complete one-to-one mapping.
.TP
.B "hfs version"
The current running version of
.B hfsutils
is returned.
.TP
.B "hfs copyright"
A copyright notice is returned.
.TP
.B "hfs author"
The name and email address of the author of
.B hfsutils
is returned.
.TP
.B "hfs license"
A license statement for
.B hfsutils
is returned.
.TP
.IB "vol " vname
The volume name of the given
.I vol
handle is returned. This is also the name of the volume's root directory,
needed to construct absolute pathnames on the volume.
.TP
.IB "vol " size
A list of two numbers is returned; the first is the total size of the given
.I vol
(in bytes), and the second is the number of free bytes that are currently
available.
.TP
.IB "vol " crdate
The creation date of the given
.I vol
is returned, expressed as a number of seconds since 00:00:00 01-Jan-1970 UTC.
.TP
.IB "vol " mddate
The last modification date of the given
.I vol
is returned, expressed as a number of seconds since 00:00:00 01-Jan-1970 UTC.
.TP
.IB "vol " islocked
A boolean value (either 1 or 0) is returned, indicating whether the given
.I 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).
.TP
.IB "vol " umount
The indicated
.I vol
is unmounted, flushing any unsaved data to the volume and closing the access
path to the medium. The
.I vol
handle subsequently becomes invalid for further use.
.TP
.IB "vol " cwd
A numeric value is returned indicating the catalog node ID (CNID) of the
current working directory on the given
.IR vol .
This value can be passed to
.IB "vol " dirinfo
to learn the directory's name and parent CNID.
.TP
.IB "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
.IB "vol " sepchar
characters (:) to construct an absolute pathname to the current directory.
.IP
The same information can be acquired by traversing the CNIDs from the current
directory to the root using
.I vol
.BR dirinfo .
(The root directory always has a CNID of 2.)
.TP
.IB "vol " dir " [path]"
A list is returned describing the contents of the given directory
.I path
(defaulting to the current directory) on the given
.IR 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
.BR "array set" .
.TP
.IB "vol " flush
All pending changes to the given volume are flushed immediately.
.TP
.IB "vol " sepchar
The HFS path separator character ":" is returned.
.TP
.IB "vol " cd " path"
.PD 0
.TP
.IB "vol " chdir " path"
.PD 1
The current working directory on the given volume is changed to
.IR path ,
which may be either an absolute or relative path.
.TP
.IB "vol " dirinfo " cnid"
A two-element list describing the directory having the given
.I cnid
on the given
.I 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.
.TP
.IB "vol " open " path"
The file on
.I vol
having the given
.I path
is opened. An HFS file handle is returned, which may be used for further file
commands described below.
.TP
.IB "vol " stat " path"
Information about the file or directory having the given
.I path
is returned in much the same way as
.IB "vol " dir
except that only the single argument is described (not its contents).
.TP
.IB "vol " mkdir " path"
A new directory on
.I vol
having the given
.I path
is created. All of the parent directories leading to
.I path
must already exist, but
.I path
itself must not.
.TP
.IB "vol " rmdir " path"
The directory on
.I vol
with the given
.I path
is removed. The directory must be empty.
.TP
.IB "vol " delete " path"
The file on
.I vol
with the given
.I path
is removed. Both resource and data forks of the file are deleted.
.TP
.IB "vol " touch " path"
The modification time for the file or directory specified by
.I path
on the given
.I vol
is updated to the current time.
.TP
.IB "vol " glob " pattern"
The given
.I 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
.I 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.
.TP
.IB "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.
.TP
.IB "vol " rename " oldpath newpath"
The existing
.I oldpath
on the given
.I vol
is renamed to
.IR newpath ,
possibly changing its location at the same time. If
.I 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.)
.TP
.IB "vol " create " path type creator"
A new, empty file is created on
.I vol
having the given
.IR path ,
and an HFS file handle is returned in the same manner as
.I vol
.BR open .
The file is given the specified MacOS
.I type
and
.I creator
codes, which must be 4 character strings.
.TP
.IB "vol " copy " srcpath dstvol dstpath"
The given file
.I srcpath
located on
.I vol
is copied to
.I dstpath
located on
.I dstvol
(which may be the same as
.IR vol ).
The file and its attributes are copied verbatim; no translation is performed.
.TP
.IB "vol " copyin " mode srcpath dstpath"
The specified local (UNIX)
.I srcpath
is copied into the given
.I vol
as a file having the specified (HFS)
.IR dstpath .
A translation
.I mode
must be given as one of
.BR macbinary ,
.BR binhex ,
.BR text ,
or
.BR raw .
.TP
.IB "vol " copyout " mode srcpath dstpath"
The specified (HFS)
.I srcpath
on the given
.I vol
is copied out as a local file having the specified (UNIX)
.IR dstpath .
A translation
.I mode
must be given as one of
.BR macbinary ,
.BR binhex ,
.BR text ,
or
.BR raw .
.TP
.IB "file " close
The indicated
.I file
is closed, all pending changes to the file are flushed, and the file handle
becomes invalid for any subsequent operation.
.TP
.IB "file " tell
A numeric index is returned indicating the character position within
.I file
at which the next read or write operation will occur.
.TP
.IB "file " stat
Information about the given
.I file
is returned in much the same way as
.I vol
.BR stat .
.TP
.IB "file " getfork
If the given
.I 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
.I file
.BR setfork .
.TP
.IB "file " setfork " fork"
The current fork of the given
.I file
is set to
.I fork
(which must be one of
.B data
or
.BR rsrc ),
and the current read/write position is reset to the beginning of the file.
.TP
.IB "file " seek " pos [from]"
The character position for the next read or write on
.I file
is changed to
.IR pos ,
relative to the indicated
.I from
position, which must be one of
.BR start ,
.BR current ,
or
.BR end .
The default is to position relative to the
.B start
of the file.
.TP
.IB "file " read " length"
.I length
bytes are read from the current read/write position in
.IR file ,
and these bytes are returned as a string. This string may be shorter than
.I length
in some circumstances, or may even be empty, indicating the end of the file
has been reached.
.TP
.IB "file " write " string"
The given
.I string
is written to
.I 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).
.SH SEE ALSO
hfsutils(1), hfs(1), tclsh(1)
.SH 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
.B "hfs flushall"
may help reduce this risk.
.SH 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.
.SH AUTHOR
Robert Leslie <rob@mars.org>