Ubuntu Manpage: hfssh - Tcl interpreter with HFS extensions

Provided by: hfsutils-tcltk_3.2.6-12ubuntu3_amd64

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).

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