| 1 |
.\" Copyright 2025, Jason Yundt <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pathname 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pathname, |
| 9 |
filename |
| 10 |
\- |
| 11 |
how pathnames are encoded and interpreted |
| 12 |
.SH DESCRIPTION |
| 13 |
Some system calls allow you to pass a pathname as a parameter. |
| 14 |
When writing code that deals with pathnames, |
| 15 |
there are kernel-space requirements that you must comply with, |
| 16 |
and user-space requirements that you should comply with. |
| 17 |
.P |
| 18 |
The kernel stores pathnames as C strings, |
| 19 |
that is, |
| 20 |
sequences of non-null bytes terminated by a null byte. |
| 21 |
There are a few general rules that apply to all pathnames: |
| 22 |
.IP \[bu] 3 |
| 23 |
The last byte in the sequence needs to be a null byte. |
| 24 |
.IP \[bu] |
| 25 |
Any other bytes in the sequence need to be non-null bytes. |
| 26 |
.IP \[bu] |
| 27 |
A 0x2F byte |
| 28 |
.RI ( \[aq]/\[aq] ) |
| 29 |
is always interpreted as a directory separator, |
| 30 |
and cannot be part of a filename. |
| 31 |
.IP \[bu] |
| 32 |
A pathname can be at most |
| 33 |
.B PATH_MAX |
| 34 |
bytes long |
| 35 |
(see |
| 36 |
.BR limits.h (0p)). |
| 37 |
A pathname that's longer than |
| 38 |
.B PATH_MAX |
| 39 |
bytes |
| 40 |
can be split into multiple smaller pathnames |
| 41 |
and opened piecewise using |
| 42 |
.BR openat (2). |
| 43 |
.IP \[bu] |
| 44 |
A filename can be at most a certain number of bytes long. |
| 45 |
The number is filesystem-specific |
| 46 |
(see |
| 47 |
.B _PC_NAME_MAX |
| 48 |
in |
| 49 |
.BR fpathconf (3)). |
| 50 |
For maximum portability, |
| 51 |
programs should be able to |
| 52 |
handle filenames that are as long as the relevant filesystems will allow. |
| 53 |
For maximum portability, |
| 54 |
programs and users should |
| 55 |
limit the length of their own pathnames to |
| 56 |
.B NAME_MAX |
| 57 |
bytes |
| 58 |
(see |
| 59 |
.BR limits.h (0p)). |
| 60 |
.P |
| 61 |
Some filesystems or APIs may apply further restrictions, |
| 62 |
such as requiring shorter filenames, |
| 63 |
or restricting the allowed bytes in a filename. |
| 64 |
.P |
| 65 |
For maximum interoperability, |
| 66 |
programs and users should also |
| 67 |
limit the characters that they use for their own pathnames to |
| 68 |
characters in the POSIX |
| 69 |
.UR https:\://pubs.opengroup.org/\:onlinepubs/\:9799919799/\:basedefs/\:V1_chap03.html#tag_03_265 |
| 70 |
Portable Filename Character Set |
| 71 |
.UE . |
| 72 |
.SH VERSIONS |
| 73 |
POSIX.1-2024 encourages implementations to |
| 74 |
disallow creation of filenames containing new-line characters. |
| 75 |
Linux doesn't follow this, |
| 76 |
and allows using new-line characters. |
| 77 |
.SH SEE ALSO |
| 78 |
.BR limits.h (0p), |
| 79 |
.BR open (2), |
| 80 |
.BR fpathconf (3), |
| 81 |
.BR path_resolution (7), |
| 82 |
.BR mount (8) |