HFSSH(1)

💖 HFSSH 💖

okay bestie, so this is hfssh(1) — it lives in the General Commands Manual section, and it's literally the moment Tcl got a glow-up for Macintosh HFS media. buckle up 🎀

---

✨ NAME ✨

hfssh — a Tcl interpreter with HFS extensions 🦋

---

🌸 SYNOPSIS 🌸

hfssh [script]

---

👑 DESCRIPTION 👑

So. hfssh is a Tcl interpreter, like tclsh(1), except it also implements the following extensions to support manipulation of Macintosh HFS media. no cap, it's tclsh but with the Macintosh lore unlocked 💅

---

🗂️ the hfs commands

hfs mount path [partno]

Mounts the indicated HFS partition from the given path. You get back an HFS volume handle, which you can then use for all the further volume commands described below. keep it safe, it's your little key 🔑

hfs zero path nparts

The given path gets overwritten with a Macintosh partition structure which can accommodate up to nparts partitions. All the space on the medium is initially allocated to an empty partition, and from that empty partition you can create new ones using hfs mkpart. The number of blocks in this empty space available for partitioning is returned. 🌱

hfs mkpart path nblocks

A brand new HFS partition gets created from the available free space on the specified Macintosh-partitioned medium. It's 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. So it's genuinely best to think about this when you're initially creating the total number of partition slots with hfs zero. plan ahead bestie, future you will be so grateful 😭

hfs nparts path

Returns the number of HFS partitions that exist on the Macintosh-formatted medium specified by path. If path doesn't appear to have a Macintosh partition map, or if an error happens, this command returns -1. Otherwise it returns a number greater than or equal to 0. 💫

hfs format path partno vname [bblist]

Creates a whole new HFS volume by formatting the given path and partition partno, and giving it a volume label vname. 🎀

If you want to "spare" some blocks from being used by the volume, you can hand over a list of "bad block" numbers, relative to the beginning of the partition. Those 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. do it, do it often, protect your data 🧚

hfs chartrans fromset toset string

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. it's giving "some things just don't translate" 💀

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.

---

💜 the vol commands

vol vname

The volume name of the given vol handle is returned. This is also the name of the volume's root directory — which you need in order 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. say your goodbyes, it's over 😭

vol cwd

A numeric value is returned indicating the catalog node ID (CNID) of the current working directory on the given vol. You can pass this value 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.) iykyk 💅

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 you can use for all the 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. no double-creating bestie 🙈

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. both of them. gone. 💀

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

---

🎀 the file commands

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

---

and bestie… that's not even all of it. part 2 is loading, stay tuned 👀

• file read length — bestie, this one pulls length bytes straight out of file, starting from wherever the current read/write position is sitting, and hands them back to you as a string. ✨ Heads up tho: that string can be shorter than length in some circumstances, and it can even come back empty — which is the vibe check that says you've hit the end of the file. 🌸
• file write string — writes the string you give it into file at the current read/write position. It returns the number of bytes that actually made it onto the file, which — in unusual circumstances, like when the volume is full 💀 — may be less than the length of your string. So don't just assume it all landed, okay?

---

💖 SEE ALSO 💖

• hfsutils(1)
• hfs(1)
• tclsh(1)

---

🫶 NOTES 🫶

Okay so the shell is trying to be a good friend here: precautions are taken to make sure all open files and mounted volumes get cleanly closed and unmounted before it exits. Very responsible. Very demure. 🎀

But — and I need you to hear me on this — abnormal termination (e.g. CTRL-C) can totally circumvent that whole process, and that can potentially leave your volumes in an inconsistent state. 😭 Not the cute kind of chaos.

Using hfs flushall judiciously may help reduce this risk. Key word: judiciously. Don't go feral with it. 💅

---

💀 BUGS 💀

Tcl does not provide a mechanism for manipulating arbitrary binary data. That's just the way it is, no cap.

So please, use caution when reading or writing files containing anything other than plain text. Binary files in a Tcl string? It's giving risky. 🙈

---

👑 AUTHOR 👑

Robert Leslie <rob@mars.org>

---

That's the whole page, bestie — HFSUTILS, version 19-Feb-1998, filed under HFSSH(1). Old school, but iconic. Now go unmount your volumes properly. 🦋💜