mirror of https://github.com/mkerrisk/man-pages
283 lines
10 KiB
Plaintext
283 lines
10 KiB
Plaintext
.\" 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 .
|