MH-FOLDERS(5)

💖 mh-folders(5) 💖

okay so bestie, this is the tea on the storage format that the nmh message system uses. File Formats Manual energy, but make it cute. Let's get into it 🫶

---

✨ NAME ✨

mh-folders — the storage format used by the nmh message system, no cap

---

🌸 DESCRIPTION 🌸

So here's the whole vibe: nmh keeps your messages in the files and directories of the host filesystem, and it follows these rules, periodt:

🗂️ one folder per directory

An nmh folder is a directory. That's it, that's the whole thing. And there are literally no limits on folder names beyond whatever limits the host filesystem itself has. Go off, name your folders whatever.

💌 one message per file

The file name is a positive integer. Yes, a number. That's the name. 🎀

Other files can absolutely live in a folder — stuff holding metadata, files with arbitrary names, all of it. The preference is that non-message files start with a ., but here's the rule: all files that are not positive integers must be ignored by an MH-compatible implementation. Must. Ignored. However — and this is the fun part — implementations are free to tell the user that non-message files exist if those files aren't prefixed with a .. So like, they can tattle, but they can't touch.

The filename for a new message is one greater than the highest numbered message in the folder. Its full path can be reached via the pseudo-sequence new (e.g. mhpath new). And here's a hard rule: new messages are only permitted to be added to a folder at the end of the message number range. No sneaking them in the middle, bestie.

To add a new message to a folder, the recommended sequence is:

• Create a temporary file in the desired folder.
• Attempt to link the temporary file to the new message number.
• If successful, remove the temporary file. If the link fails, increment the message number and try again.

slay, that's the algorithm 💅

📝 context

There is one context file. Its default location is in the user's Path and its default name is context, but both of those can be overridden by the $MHCONTEXT environment variable. The context file has this format:

Current-Folder: +folder
atr-sequence-path: m[-n] [...]

where folder is the directory name of the current folder. Lines starting with atr are used for private sequences. sequence is the name of the private sequence, path is the full path to the folder with the private sequence, and m[-n] is a message number or a range of message numbers in the sequence. iykyk 🌈

🧵 sequences

There is one sequences file in each nmh folder. Its default name is .mh_sequences, but that can be overridden by the mh-sequences profile entry. The sequences file has this format:

sequence: m[-n] [...]

showing the (possibly empty) message numbers and/or ranges of message numbers in each sequence. Heads up: the cur sequence has at most just a single message number, not a range. Not a range!! 🚨

Sequence names have a maximum size of 998 characters. Each line is also limited to a maximum of 998 characters, but RFC 822 continuation rules apply — so sequences can be continued across multiple lines by prefixing continuation lines with a whitespace character. Multiline glow-up ✨

If an implementation finds messages in a sequence that do not exist, the sequence file should be updated to remove the missing messages from the sequence. And if a sequence contains no messages, it should be removed from the sequence file entirely. The exception to this is the cur sequence, which can refer to a nonexistent message. Yeah, cur gets special treatment. main character energy, honestly. 👑

---

🔒 Locking

nmh programs read and write the context and sequences files, and they lock these files when accessing them. There should not be a need to access these files directly — instead, use programs like flist, folder, mark, pick, and rcvstore to query and update their contents. That's what they're for, bestie, use them 🙈

Any program outside of nmh that accesses these files must be sure to lock them using the same locking method as nmh. Do not skip this. Do not freestyle this.

The default data locking method is selected when nmh is configured, and it can be accessed as a string using mhparam datalocking. By default, fcntl locking is used, but this may be overridden by the datalocking profile entry.

There's a second, possibly different, locking method used by inc(1) when accessing the user's mail spool file, or by nmh programs that open any mbox file. This locking method can be overridden when nmh is configured, or in the nmh mts configuration file, and it can be accessed as a string using mhparam spoollocking. By default, kernel-level locking is used if that's appropriate for the platform — and it is, for popular platforms. That default should also be the same as what the mail program uses, if the platform provides one. Consistency queen 💖

---

🏷️ Naming

nmh folders can be given arbitrary names, with one exception: folders should not be given all-numeric names. Why? Because nmh messages themselves are stored in numerically named files — letting folders be named the same way would make nmh slower, and would introduce usage ambiguities. So like… don't. Please. For all of us. 😭

---

📁 FILES 📁

• <mh-dir>/context — The user's context.
• $MHCONTEXT — Overrides the above context.
• <folder>/.mh_sequences — Public sequences for <folder>.

---

👀 SEE ALSO 👀

flist(1), folder(1), mail(1), mark(1), mhparam(1), mhpath(1), mh-profile(5), mh-sequence(5), mh-tailor(5), pick(1), rcvstore(1)

---

and that's the whole page, bestie!! 🦋 this was nmh-1.8, dated 2016-02-25, and yeah, that's genuinely the vintage. iconic of it. go forth and format your folders correctly 💅💖✨