.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FPATHCONF" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" fpathconf 
.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 \- 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 .