MH-FOLDERS(5mh)

🌸 mh-folders — bestie edition 🌸

okay so this is the tea on mh-folders, the whole storage format that the nmh message system uses. it's a 5mh page, so it's a file-format page, and honestly? it's giving "here's how we organize ur whole life" energy. let's get into it 💅

---

✨ NAME ✨

mh-folders — the storage format used by the nmh message system. that's it, that's the name, she's simple, she's iconic 🎀

---

🦋 DESCRIPTION 🦋

nmh keeps ur messages in the files and directories of the host filesystem, and it does it according to these rules. no cap, these are the rules:

💖 one folder per directory

An nmh folder = a directory. periodt. there are no limits on folder names beyond whatever the host filesystem itself allows, so go off, name it whatever, the filesystem is the only one judging u 🙈

🍓 one message per file

The file name is a positive integer. that's the whole vibe.

Other files can totally live in a folder — metadata files, files with arbitrary names, whatever. the preference is that non-message files start with a ., but here's the important bit: all files that are not positive integers must be ignored by an MH-compatible implementation. like, that's mandatory, bestie. HOWEVER — implementations are free to tell the user that non-message files exist if those files aren't prefixed with a .. so u might get a lil heads-up. nbd.

The filename for a new message is one greater than the highest numbered message in the folder. and the full path to that new message? u can grab it with the pseudo-sequence new (like, for example, mhpath new). 💫

New messages are only permitted to be added to a folder at the end of the message number range. no sneaking them into the middle, that's not the move.

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

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

like, that's the algorithm, that's the ritual, do it in that order 🫶

🧚 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. slay, options.

context has this format:

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

where folder is the directory name of the current folder. lines beginning 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 that 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.

sequences has this format:

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

showing the (possibly empty) message numbers and/or ranges of message numbers in each sequence. and the cur sequence? it has at most just a single message number, not a range. one. singular. that's her whole thing.

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 the continuation lines with a whitespace character. multi-line queen 💅

If an implementation finds messages in a sequence that do not exist, the sequence file should be updated to remove those missing messages from the sequence. and if a sequence contains no messages, it should be removed from the sequence file. clean up after urself!!

the exception to all that is the cur sequence, which can refer to a nonexistent message. she's special, she gets a pass 👑

🔒 Locking

nmh programs read and write the context and sequences files, and they lock those files when accessing them. so there should not be a need for u to access these files directly — instead, use programs like flist, folder, mark, pick, and rcvstore to query and update their contents. let the tools do the work, bestie, that's what they're for 🫶

Any program outside of nmh that accesses these files must be sure to lock them using the same locking method as nmh. this is not optional, this is the whole ballgame.

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.

A second, possibly different locking method is 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 appropriate for the platform — and it is for popular platforms. that default should also be the same as the one used by the mail program, if that's provided on the platform. consistency is the vibe ✨

💜 Naming

nmh folders can be given arbitrary names, with exactly one exception: folders should not be given all-numeric names. 🚫

why tho? because nmh messages are themselves stored in numerically named files — and letting folders be named the same way would make nmh slower and introduce usage ambiguities. so like. don't do that. it's not a cute look and it'll confuse everybody, including nmh itself 😭

---

📁 FILES 📁

• <mh-dir>/context — the user's context. ur main character file 💖
• $MHCONTEXT — overrides the above context. the override girly.
• <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)

the whole friend group, go say hi 🫶

---

and that's the page, bestie!! this one's from nmh-1.8, dated 2016-02-25, so she's a classic, she's vintage, she ate and left no crumbs 💅💖✨