diff options
Diffstat (limited to 'man3p/pathconf.3p')
| -rw-r--r-- | man3p/pathconf.3p | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/man3p/pathconf.3p b/man3p/pathconf.3p new file mode 100644 index 000000000..cfb5be873 --- /dev/null +++ b/man3p/pathconf.3p @@ -0,0 +1,282 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FPATHCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fpathconf +.SH NAME +fpathconf, pathconf \- get configurable pathname variables +.SH SYNOPSIS +.LP +\fB#include <unistd.h> +.br +.sp +long fpathconf(int\fP \fIfildes\fP\fB, int\fP \fIname\fP\fB); +.br +long pathconf(const char *\fP\fIpath\fP\fB, int\fP \fIname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIfpathconf\fP() and \fIpathconf\fP() functions shall determine +the current value of a configurable limit or option +(\fIvariable\fP) that is associated with a file or directory. +.LP +For \fIpathconf\fP(), the \fIpath\fP argument points to the pathname +of a file or directory. +.LP +For \fIfpathconf\fP(), the \fIfildes\fP argument is an open file descriptor. +.LP +The \fIname\fP 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 \fI<limits.h>\fP +or \fI<unistd.h>\fP and the +symbolic constants, defined in \fI<unistd.h>\fP, are the corresponding +values used +for \fIname\fP. +.TS C +center; l2 l2 l. +\fBVariable\fP \fBValue of \fIname\fP\fP \fBRequirements\fP +{FILESIZEBITS} _PC_FILESIZEBITS 3,4 +{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 +{POSIX_ALLOC_SIZE_MIN} _PC_ALLOC_SIZE_MIN \ +{POSIX_REC_INCR_XFER_SIZE} _PC_REC_INCR_XFER_SIZE \ +{POSIX_REC_MAX_XFER_SIZE} _PC_REC_MAX_XFER_SIZE \ +{POSIX_REC_MIN_XFER_SIZE} _PC_REC_MIN_XFER_SIZE \ +{POSIX_REC_XFER_ALIGN} _PC_REC_XFER_ALIGN \ +{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 +.TE +.SS Requirements +.IP " 1." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to the directory itself. +.LP +.IP " 2." 4 +If \fIpath\fP or \fIfildes\fP does not refer to a terminal file, it +is unspecified whether an implementation supports an +association of the variable name with the specified file. +.LP +.IP " 3." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to filenames within the directory. +.LP +.IP " 4." 4 +If \fIpath\fP or \fIfildes\fP does not refer to a directory, it is +unspecified whether an implementation supports an +association of the variable name with the specified file. +.LP +.IP " 5." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall be the maximum length of a relative pathname +when the specified directory is the working directory. +.LP +.IP " 6." 4 +If \fIpath\fP refers to a FIFO, or \fIfildes\fP refers to a pipe or +FIFO, the value returned shall apply to the referenced +object. If \fIpath\fP or \fIfildes\fP refers to a directory, the value +returned shall apply to any FIFO that exists or can be +created within the directory. If \fIpath\fP or \fIfildes\fP refers +to any other type of file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.LP +.IP " 7." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall apply to any files, other than directories, that +exist or can be created within the directory. +.LP +.IP " 8." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, it is unspecified +whether an implementation supports an association of +the variable name with the specified file. +.LP +.IP " 9." 4 +If \fIpath\fP or \fIfildes\fP refers to a directory, the value returned +shall be the maximum length of the string that a +symbolic link in that directory can contain. +.LP +.SH RETURN VALUE +.LP +If \fIname\fP is an invalid value, both \fIpathconf\fP() and \fIfpathconf\fP() +shall return -1 and set \fIerrno\fP to +indicate the error. +.LP +If the variable corresponding to \fIname\fP has no limit for the \fIpath\fP +or file descriptor, both \fIpathconf\fP() and +\fIfpathconf\fP() shall return -1 without changing \fIerrno\fP. If +the implementation needs to use \fIpath\fP to determine the +value of \fIname\fP and the implementation does not support the association +of \fIname\fP with the file specified by \fIpath\fP, +or if the process did not have appropriate privileges to query the +file specified by \fIpath\fP, or \fIpath\fP does not exist, +\fIpathconf\fP() shall return -1 and set \fIerrno\fP to indicate the +error. +.LP +If the implementation needs to use \fIfildes\fP to determine the value +of \fIname\fP and the implementation does not support +the association of \fIname\fP with the file specified by \fIfildes\fP, +or if \fIfildes\fP is an invalid file descriptor, +\fIfpathconf\fP() shall return -1 and set \fIerrno\fP to indicate +the error. +.LP +Otherwise, \fIpathconf\fP() or \fIfpathconf\fP() shall return the +current variable value for the file or directory without +changing \fIerrno\fP. The value returned shall not be more restrictive +than the corresponding value available to the application +when it was compiled with the implementation's \fI<limits.h>\fP or +\fI<unistd.h>\fP. +.SH ERRORS +.LP +The \fIpathconf\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIname\fP is not valid. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.sp +.LP +The \fIpathconf\fP() function may fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix. +.TP 7 +.B EINVAL +The implementation does not support an association of the variable +\fIname\fP with the specified file. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIfpathconf\fP() function shall fail if: +.TP 7 +.B EINVAL +The value of \fIname\fP is not valid. +.sp +.LP +The \fIfpathconf\fP() function may fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINVAL +The implementation does not support an association of the variable +\fIname\fP with the specified file. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIpathconf\fP() function was proposed immediately after the \fIsysconf\fP() +function when it was realized that some configurable values may differ +across file system, directory, or device boundaries. +.LP +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 \fI<limits.h>\fP +on such a +system. +.LP +Therefore, various useful values can be queried on any pathname or +file descriptor, assuming that the appropriate permissions +are in place. +.LP +The value returned for the variable {PATH_MAX} indicates the longest +relative pathname that could be given if the specified +directory is the process' current working directory. 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. +.LP +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\fP() function and look for an +error in case it +happens.) +.LP +Unlike the values returned by \fIsysconf\fP(), the pathname-oriented +variables are +potentially more volatile and are not guaranteed to remain constant +throughout the process' lifetime. For example, in between two +calls to \fIpathconf\fP(), the file system in question may have been +unmounted and remounted with different characteristics. +.LP +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 \fIpath\fP or \fIfildes\fP 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 \fIname\fP is not valid for that variable. +.LP +If the value of any of the limits is unspecified (logically infinite), +they will not be defined in \fI<limits.h>\fP and the \fIpathconf\fP() +and \fIfpathconf\fP() functions return -1 +without changing \fIerrno\fP. This can be distinguished from the case +of giving an unrecognized \fIname\fP argument because +\fIerrno\fP is set to [EINVAL] in this case. +.LP +Since -1 is a valid return value for the \fIpathconf\fP() and \fIfpathconf\fP() +functions, applications should set +\fIerrno\fP to zero before calling them and check \fIerrno\fP only +if the return value is -1. +.LP +For the case of {SYMLINK_MAX}, since both \fIpathconf\fP() and \fIopen\fP() +follow +symbolic links, there is no way that \fIpath\fP or \fIfildes\fP could +refer to a symbolic link. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIconfstr\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI<limits.h>\fP, \fI<unistd.h>\fP, the Shell +and Utilities volume of IEEE\ Std\ 1003.1-2001 +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |