diff options
Diffstat (limited to 'upstream/archlinux/man3p/fpathconf.3p')
| -rw-r--r-- | upstream/archlinux/man3p/fpathconf.3p | 514 |
1 files changed, 514 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/fpathconf.3p b/upstream/archlinux/man3p/fpathconf.3p new file mode 100644 index 00000000..d9bbc0c1 --- /dev/null +++ b/upstream/archlinux/man3p/fpathconf.3p @@ -0,0 +1,514 @@ +'\" et +.TH FPATHCONF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +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. +.\" +.SH NAME +fpathconf, +pathconf +\(em get configurable pathname variables +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +long fpathconf(int \fIfildes\fP, int \fIname\fP); +long pathconf(const char *\fIpath\fP, int \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIfpathconf\fR() +and +\fIpathconf\fR() +functions shall determine the current value of a configurable limit or +option (\fIvariable\fP) that is associated with a file or directory. +.P +For +\fIpathconf\fR(), +the +.IR path +argument points to the pathname of a file or directory. +.P +For +\fIfpathconf\fR(), +the +.IR fildes +argument is an open file descriptor. +.P +The +.IR 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 +.IR <limits.h> +or +.IR <unistd.h> +and the symbolic constants, defined in +.IR <unistd.h> , +are the corresponding values used for +.IR name . +.TS +center box tab(!); +cB | cB | cB +l | l | l. +Variable!Value of \fIname\fP!Requirements +_ +{FILESIZEBITS}!_PC_FILESIZEBITS!4,\|7 +{LINK_MAX}!_PC_LINK_MAX!1 +{MAX_CANON}!_PC_MAX_CANON!2 +{MAX_INPUT}!_PC_MAX_INPUT!2 +{NAME_MAX}!_PC_NAME_MAX!3,\|4 +{PATH_MAX}!_PC_PATH_MAX!4,\|5 +{PIPE_BUF}!_PC_PIPE_BUF!6 +{POSIX2_SYMLINKS}!_PC_2_SYMLINKS!4 +{POSIX_ALLOC_SIZE_MIN}!_PC_ALLOC_SIZE_MIN!10 +{POSIX_REC_INCR_XFER_SIZE}!_PC_REC_INCR_XFER_SIZE!10 +{POSIX_REC_MAX_XFER_SIZE}!_PC_REC_MAX_XFER_SIZE!10 +{POSIX_REC_MIN_XFER_SIZE}!_PC_REC_MIN_XFER_SIZE!10 +{POSIX_REC_XFER_ALIGN}!_PC_REC_XFER_ALIGN!10 +{SYMLINK_MAX}!_PC_SYMLINK_MAX!4,\|9 +_POSIX_CHOWN_RESTRICTED!_PC_CHOWN_RESTRICTED!7 +_POSIX_NO_TRUNC!_PC_NO_TRUNC!3,\|4 +_POSIX_VDISABLE!_PC_VDISABLE!2 +_POSIX_ASYNC_IO!_PC_ASYNC_IO!8 +_POSIX_PRIO_IO!_PC_PRIO_IO!8 +_POSIX_SYNC_IO!_PC_SYNC_IO!8 +_POSIX_TIMESTAMP_RESOLUTION!_PC_TIMESTAMP_RESOLUTION!1 +.TE +.SS "Requirements" +.IP " 1." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to the directory +itself. +.IP " 2." 4 +If +.IR path +or +.IR 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. +.IP " 3." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to filenames +within the directory. +.IP " 4." 4 +If +.IR path +or +.IR fildes +does not refer to a directory, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 5." 4 +If +.IR path +or +.IR 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. +.IP " 6." 4 +If +.IR path +refers to a FIFO, or +.IR fildes +refers to a pipe or FIFO, the value returned shall apply to the +referenced object. If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to any FIFO that +exists or can be created within the directory. If +.IR path +or +.IR 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. +.IP " 7." 4 +If +.IR path +or +.IR 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. +.IP " 8." 4 +If +.IR path +or +.IR fildes +refers to a directory, it is unspecified whether an implementation +supports an association of the variable name with the specified file. +.IP " 9." 4 +If +.IR path +or +.IR 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. +.IP 10. 4 +If +.IR path +or +.IR fildes +des 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. +.SH "RETURN VALUE" +If +.IR name +is an invalid value, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +If the variable corresponding to +.IR name +is described in +.IR <limits.h> +as a maximum or minimum value and the variable has no limit for the +path or file descriptor, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \-1 without changing +.IR errno . +Note that indefinite limits do not imply infinite limits; see +.IR <limits.h> . +.P +If the implementation needs to use +.IR path +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR path , +or if the process did not have appropriate privileges to query the +file specified by +.IR path , +or +.IR path +does not exist, +\fIpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +If the implementation needs to use +.IR fildes +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR fildes , +or if +.IR fildes +is an invalid file descriptor, +\fIfpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +Otherwise, +\fIpathconf\fR() +or +\fIfpathconf\fR() +shall return the current variable value for the file or directory +without changing +.IR 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 +.IR <limits.h> +or +.IR <unistd.h> . +.P +If the variable corresponding to +.IR name +is dependent on an unsupported option, the results are unspecified. +.SH ERRORS +The +\fIpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.br +.P +The +\fIpathconf\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENAMETOOLONG +.br +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}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR 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 +.IR path +argument contains at least one non-\c +<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. +.P +The +\fIfpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.P +The +\fIfpathconf\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "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}. +.SH RATIONALE +The +\fIpathconf\fR() +function was proposed immediately after the +\fIsysconf\fR() +function when it was realized that some configurable values may differ +across file system, directory, or device boundaries. +.P +For example, +{NAME_MAX} +frequently changes between System V and +BSD-based file systems; System V uses a maximum of 14, BSD 255. On an +implementation that provides both types of file systems, an application +would be forced to limit all pathname components to 14 bytes, as this +would be the value specified in +.IR <limits.h> +on such a system. +.P +Therefore, various useful values can be queried on any pathname or file +descriptor, assuming that appropriate privileges +are in place. +.P +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. +.P +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 +\fIchown\fR() +function and look for an error in case it happens.) +.P +Unlike the values returned by +\fIsysconf\fR(), +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 +\fIpathconf\fR(), +the file system in question may have been unmounted and remounted with +different characteristics. +.P +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 +.IR path +or +.IR fildes +to return that value and is, therefore, not required to detect +any of the errors except the meaning of +.BR [EINVAL] +that indicates that the value of +.IR name +is not valid for that variable, and the +.BR [EOVERFLOW] +error that indicates the value to be returned is larger than +{LONG_MAX}. +.P +If the value of any of the limits is unspecified (logically +infinite), they will not be defined in +.IR <limits.h> +and the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions return \-1 without changing +.IR errno . +This can be distinguished from the case of giving an unrecognized +.IR name +argument because +.IR errno +is set to +.BR [EINVAL] +in this case. +.P +Since \-1 is a valid return value for the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions, applications should set +.IR errno +to zero before calling them and check +.IR errno +only if the return value is \-1. +.P +For the case of +{SYMLINK_MAX}, +since both +\fIpathconf\fR() +and +\fIopen\fR() +follow symbolic links, there is no way that +.IR path +or +.IR fildes +could refer to a symbolic link. +.P +It was the intention of IEEE\ Std 1003.1d\(hy1999 that the following variables: +.sp +.RS +{POSIX_ALLOC_SIZE_MIN} +{POSIX_REC_INCR_XFER_SIZE} +{POSIX_REC_MAX_XFER_SIZE} +{POSIX_REC_MIN_XFER_SIZE} +{POSIX_REC_XFER_ALIGN} +.RE +.P +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). +.P +The +.BR [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. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<limits.h>\fP", +.IR "\fB<unistd.h>\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIgetconf\fR\^" +.\" +.SH 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 . +.PP +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 . |