Provided by: hfsutils-tcltk_3.2.6-15build2_amd64 bug

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>