mirror of
https://github.com/autc04/Retro68.git
synced 2024-09-10 03:54:48 +00:00
425 lines
11 KiB
Groff
425 lines
11 KiB
Groff
.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:
|
|
.SP
|
|
.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>
|