The goal of this new manual page is to help people create programs that do the right thing even in the face of unusual paths. The information that I used to create this new manual page came from this Unix & Linux Stack Exchange answer [1], this Libc-help mailing list post [2] and this line of code from the kernel [3]. [1]: <https://unix.stackexchange.com/a/39179/316181> [2]: <https://sourceware.org/pipermail/libc-help/2024-August/006737.html> [3]: <https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/fs/ext4/ext4.h?h=v6.12.9#n2288> Signed-off-by: Jason Yundt <jason@jasonyundt.email> --- Here’s what I changed from the previous version: • The title of the page is now “path_format”. It’s now always written in all lowercase. • The second kernel rule now uses the suggested phrase “…need to be non-null bytes”. • The manual page now recommends self-limiting to the POSIX Portable Filename Character Set. • A missing word (byte) was added to the first kernel rule. • I added a missing source to the commit message. man/man7/path_format.7 | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 man/man7/path_format.7 diff --git a/man/man7/path_format.7 b/man/man7/path_format.7 new file mode 100644 index 000000000..0a129eeba --- /dev/null +++ b/man/man7/path_format.7 @@ -0,0 +1,47 @@ +.\" Copyright (C) 2025 Jason Yundt (jason@jasonyundt.email) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH path_format 7 (date) "Linux man-pages (unreleased)" +.SH NAME +path_format \- how pathnames are encoded and interpreted +.SH DESCRIPTION +Some system calls allow you to pass a pathname as a parameter. +When writing code that deals with paths, +there are kernel space requirements that you must comply with +and userspace requirements that you should comply with. +.P +The kernel stores paths as null-terminated byte sequences. +As far as the kernel is concerned, there are only three rules for paths: +.IP \[bu] +The last byte in the sequence needs to be a null byte. +.IP \[bu] +Any other bytes in the sequence need to be non-null bytes. +.IP \[bu] +A 0x2F byte is always interpreted as a directory separator (/). +.P +This means that programs can technically do weird things +like create paths using random character encodings +or create paths without using any character encoding at all. +Filesystems may impose additional restrictions on paths, though. +For example, if you want to store a file on an ext4 filesystem, +then its filename can’t be longer than 255 bytes. +.P +Userspace treats paths differently. +Userspace applications typically expect paths to use +a consistent character encoding. +For maximum interoperability, programs should use +.BR nl_langinfo (3) +to determine the current locale’s codeset. +Paths should be encoded and decoded using the current locale’s codeset +in order to help prevent mojibake. +For maximum interoperability, +programs and users should also limit +the characters that they use for their own paths to characters in +.UR https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap03.html#tag_03_265 +the POSIX Portable Filename Character Set +.UE . +.SH SEE ALSO +.BR open (2), +.BR nl_langinfo (3), +.BR path_resolution (7) -- 2.47.0
