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>