FPATHCONF(3POSIX)

💖 FPATHCONF(3POSIX) — POSIX Programmer's Manual 💖

🌸 PROLOG 🌸

okay so first things first, bestie — this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux. no cap, always check your local man page too 💅

---

✨ NAME ✨

fpathconf, pathconf — get configurable pathname variables. periodt 💖

---

🎀 SYNOPSIS 🎀

#include <unistd.h>

long fpathconf(int fildes, int name);
long pathconf(const char *path, int name);

---

🦋 DESCRIPTION 🦋

The fpathconf() and pathconf() functions shall determine the current value of a configurable limit or option (variable) that is associated with a file or directory. it's giving "let me ask the filesystem some questions" energy ✨

For pathconf(), the path argument points to the pathname of a file or directory. like, hey bestie, which file are we talking about?

For fpathconf(), the fildes argument is an open file descriptor. already got it open? slay, use the fd instead 💅

The name argument represents the variable to be queried relative to that file or directory. Implementations shall support all of the variables listed in the following table and may support others. The variables in the following table come from <limits.h> or <unistd.h> and the symbolic constants, defined in <unistd.h>, are the corresponding values used for name.

Here's the whole variable menu, bestie — no gatekeeping:

• {FILESIZEBITS} → name: _PC_FILESIZEBITS — requirements: 4,7
• {LINK_MAX} → name: _PC_LINK_MAX — requirements: 1
• {MAX_CANON} → name: _PC_MAX_CANON — requirements: 2
• {MAX_INPUT} → name: _PC_MAX_INPUT — requirements: 2
• {NAME_MAX} → name: _PC_NAME_MAX — requirements: 3,4
• {PATH_MAX} → name: _PC_PATH_MAX — requirements: 4,5
• {PIPE_BUF} → name: _PC_PIPE_BUF — requirements: 6
• {POSIX2_SYMLINKS} → name: _PC_2_SYMLINKS — requirements: 4
• {POSIX_ALLOC_SIZE_MIN} → name: _PC_ALLOC_SIZE_MIN — requirements: 10
• {POSIX_REC_INCR_XFER_SIZE} → name: _PC_REC_INCR_XFER_SIZE — requirements: 10
• {POSIX_REC_MAX_XFER_SIZE} → name: _PC_REC_MAX_XFER_SIZE — requirements: 10
• {POSIX_REC_MIN_XFER_SIZE} → name: _PC_REC_MIN_XFER_SIZE — requirements: 10
• {POSIX_REC_XFER_ALIGN} → name: _PC_REC_XFER_ALIGN — requirements: 10
• {SYMLINK_MAX} → name: _PC_SYMLINK_MAX — requirements: 4,9
• _POSIX_CHOWN_RESTRICTED → name: _PC_CHOWN_RESTRICTED — requirements: 7
• _POSIX_NO_TRUNC → name: _PC_NO_TRUNC — requirements: 3,4
• _POSIX_VDISABLE → name: _PC_VDISABLE — requirements: 2
• _POSIX_ASYNC_IO → name: _PC_ASYNC_IO — requirements: 8
• _POSIX_PRIO_IO → name: _PC_PRIO_IO — requirements: 8
• _POSIX_SYNC_IO → name: _PC_SYNC_IO — requirements: 8
• _POSIX_TIMESTAMP_RESOLUTION → name: _PC_TIMESTAMP_RESOLUTION — requirements: 1

---

🌈 Requirements 🌈

these are the rules for what those variables actually mean, so pay attention bestie 💖

1. If path or fildes refers to a directory, the value returned shall apply to the directory itself.
2. If path or fildes does not refer to a terminal file, it is unspecified whether an implementation supports an association of the variable name with the specified file.
3. If path or fildes refers to a directory, the value returned shall apply to filenames within the directory.
4. If path or fildes does not refer to a directory, it is unspecified whether an implementation supports an association of the variable name with the specified file.
5. If path or fildes refers to a directory, the value returned shall be the maximum length of a relative pathname that would not cross any mount points when the specified directory is the working directory.
6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the value returned shall apply to the referenced object. If path or fildes refers to a directory, the value returned shall apply to any FIFO that exists or can be created within the directory. If path or fildes refers to any other type of file, it is unspecified whether an implementation supports an association of the variable name with the specified file.
7. If path or fildes refers to a directory, the value returned shall apply to any files, other than directories, that exist or can be created within the directory.
8. If path or fildes refers to a directory, it is unspecified whether an implementation supports an association of the variable name with the specified file.
9. If path or fildes refers to a directory, the value returned shall be the maximum length of the string that a symbolic link in that directory can contain.
10. If path or fildes does not refer to a regular file, it is unspecified whether an implementation supports an association of the variable name with the specified file. If an implementation supports such an association for other than a regular file, the value returned is unspecified.

---

💫 RETURN VALUE 💫

If name is an invalid value, both pathconf() and fpathconf() shall return -1 and set errno to indicate the error. bestie, that's a hard no 💀

If the variable corresponding to name is described in <limits.h> as a maximum or minimum value and the variable has no limit for the path or file descriptor, both pathconf() and fpathconf() shall return -1 without changing errno. Note that indefinite limits do not imply infinite limits; see <limits.h>. important distinction, don't get it twisted 🎀

If the implementation needs to use path to determine the value of name and the implementation does not support the association of name with the file specified by path, or if the process did not have appropriate privileges to query the file specified by path, or path does not exist, pathconf() shall return -1 and set errno to indicate the error.

If the implementation needs to use fildes to determine the value of name and the implementation does not support the association of name with the file specified by fildes, or if fildes is an invalid file descriptor, fpathconf() shall return -1 and set errno to indicate the error.

Otherwise, pathconf() or fpathconf() shall return the current variable value for the file or directory without changing errno. The value returned shall not be more restrictive than the corresponding value available to the application when it was compiled with the implementation's <limits.h> or <unistd.h>. so you get at least what you were promised at compile time, iconic ✨

If the variable corresponding to name is dependent on an unsupported option, the results are unspecified. iykyk, check your options first 💅

---

😭 ERRORS 😭

The pathconf() function shall fail if:

• EINVAL — The value of name is not valid.
• EOVERFLOW — The value of name is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than {LONG_MAX}.

The pathconf() function may fail if:

• EACCES — Search permission is denied for a component of the path prefix.
• EINVAL — The implementation does not support an association of the variable name with the specified file.
• ELOOP — A loop exists in symbolic links encountered during resolution of the path argument.
• ELOOP — More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.
• ENAMETOOLONG — The length of a component of a pathname is longer than {NAME_MAX}.
• ENAMETOOLONG — The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.
• ENOENT — A component of path does not name an existing file or path is an empty string.
• ENOTDIR — A component of the path prefix names an existing file that is neither a directory nor a symbolic link to a directory, or the path argument contains at least one non-<slash> character and ends with one or more trailing <slash> characters and the last pathname component names an existing file that is neither a directory nor a symbolic link to a directory.

The fpathconf() function shall fail if:

• EINVAL — The value of name is not valid.
• EOVERFLOW — The value of name is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than {LONG_MAX}.

The fpathconf() function may fail if:

• EBADF — The fildes argument is not a valid file descriptor.
• EINVAL — The implementation does not support an association of the variable name with the specified file.

---

The following sections are informative.

---

🌸 EXAMPLES 🌸

None. literally nothing, bestie, moving on 💅

---

💜 APPLICATION USAGE 💜

Application developers should check whether an option, such as _POSIX_ADVISORY_INFO, is supported prior to obtaining and using values for related variables such as {POSIX_ALLOC_SIZE_MIN}. so like, vibe check your options before you go querying stuff, periodt ✨

---

✨ part 2 incoming, don't go anywhere bestie ✨

💖 RATIONALE 💖

okay so storytime bestie, because the lore here is actually kinda iconic ✨

pathconf() was proposed immediately after sysconf(), right when everyone realized that some configurable values may differ across file system, directory, or device boundaries. like, they don't all live in the same house, they have different vibes depending on where you're standing 💅

for example, {NAME_MAX} frequently changes between System V and BSD-based file systems — System V uses a maximum of 14, BSD uses 255. so on an implementation that provides both types of file systems, an application would be forced to limit all pathname components to 14 bytes, because that's the value specified in <limits.h> on such a system. tragic honestly 😭

therefore, various useful values can be queried on any pathname or file descriptor, assuming that appropriate privileges are in place 🫶

---

the value returned for the variable {PATH_MAX} indicates the longest relative pathname that could be given if the specified directory is the current working directory of the process. a process may not always be able to generate a name that long and use it if a subdirectory in the pathname crosses into a more restrictive file system 🦋

note that implementations are allowed to accept pathnames longer than {PATH_MAX} bytes long, but are not allowed to return pathnames longer than this unless the user specifies a larger buffer using a function that provides a buffer size argument. read that twice bestie, it matters 👑

the value returned for the variable _POSIX_CHOWN_RESTRICTED also applies to directories that do not have file systems mounted on them. the value may change when crossing a mount point, so applications that need to know should check for each directory. (an even easier check is to try the chown() function and look for an error in case it happens. sneaky but valid 💀)

unlike the values returned by sysconf(), the pathname-oriented variables are potentially more volatile and are not guaranteed to remain constant throughout the lifetime of the process 🌪️ for example, in between two calls to pathconf(), the file system in question may have been unmounted and remounted with different characteristics. it's giving unstable, it's giving chaotic, it's giving do not cache me 🙈

---

also note that most of the errors are optional. if one of the variables always has the same value on an implementation, the implementation need not look at path or fildes to return that value, and is therefore not required to detect any of the errors except:

• the meaning of [EINVAL] that indicates that the value of name is not valid for that variable, and
• the [EOVERFLOW] error that indicates the value to be returned is larger than {LONG_MAX}.

if the value of any of the limits is unspecified (logically infinite), they will not be defined in <limits.h> and the pathconf() and fpathconf() functions return -1 without changing errno 🌸 this can be distinguished from the case of giving an unrecognized name argument because errno is set to [EINVAL] in this case. two different -1s, two different meanings, keep them straight bestie 🎀

since -1 is a valid return value for the pathconf() and fpathconf() functions, applications should set errno to zero before calling them and check errno only if the return value is -1. that's the whole ritual, no cap ✨

for the case of {SYMLINK_MAX}, since both pathconf() and open() follow symbolic links, there is no way that path or fildes could refer to a symbolic link. like, structurally impossible, the door doesn't exist 🚪💀

---

it was the intention of IEEE Std 1003.1d‐1999 that the following variables:

{POSIX_ALLOC_SIZE_MIN} {POSIX_REC_INCR_XFER_SIZE}
{POSIX_REC_MAX_XFER_SIZE} {POSIX_REC_MIN_XFER_SIZE}
{POSIX_REC_XFER_ALIGN}

only applied to regular files, but Note 10 also permits implementation of the advisory semantics on other file types unique to an implementation (for example, a character special device). so it's a vibe, not a cage 🌈

the [EOVERFLOW] error for _PC_TIMESTAMP_RESOLUTION cannot occur on POSIX-compliant file systems because POSIX requires a timestamp resolution no larger than one second ⏱️ even on 32-bit systems, this can be represented without overflow. so like, breathe, that one's fine 💜

---

🔮 FUTURE DIRECTIONS 🔮

None.

that's it. that's the whole section. the future is a blank page and honestly? main character energy 👑

---

👀 SEE ALSO 👀

• chown(), confstr(), sysconf()
• The Base Definitions volume of POSIX.1‐2017, <limits.h>, <unistd.h>
• The Shell and Utilities volume of POSIX.1‐2017, getconf

go read those too, i'm not explaining everything twice 🫶

---

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page bestie!! 💖✨🎀🦋🌸💅🫶

this lil masterpiece came to you courtesy of IEEE/The Open Group, dated 2017, filed under FPATHCONF(3POSIX) — and that's on periodt 👑💜 no cap, go check your path limits responsibly 😭🍓