fpathconf.html

IEEE 1003.1-2003, Single Unix Specification v3

<h5><a name="tag_03_178_03_01"></a>Requirements</h5>

<ol>
<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall apply to the directory itself.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> does not refer to a terminal file, it is unspecified whether an implementation supports an
association of the variable name with the specified file.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall apply to filenames within the directory.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> does not refer to a directory, it is unspecified whether an implementation supports an
association of the variable name with the specified file.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall be the maximum length of a relative pathname
when the specified directory is the working directory.</p>
</li>

<li>
<p>If <i>path</i> refers to a FIFO, or <i>fildes</i> refers to a pipe or FIFO, the value returned shall apply to the referenced
object. If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall apply to any FIFO that exists or can be
created within the directory. If <i>path</i> or <i>fildes</i> refers to any other type of file, it is unspecified whether an
implementation supports an association of the variable name with the specified file.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall apply to any files, other than directories, that
exist or can be created within the directory.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, it is unspecified whether an implementation supports an association of
the variable name with the specified file.</p>
</li>

<li>
<p>If <i>path</i> or <i>fildes</i> refers to a directory, the value returned shall be the maximum length of the string that a
symbolic link in that directory can contain.</p>
</li>
</ol>
</blockquote>

<h4><a name="tag_03_178_04"></a>RETURN VALUE</h4>

<blockquote>
<p>If <i>name</i> is an invalid value, both <i>pathconf</i>() and <i>fpathconf</i>() shall return -1 and set <i>errno</i> to
indicate the error.</p>

<p>If the variable corresponding to <i>name</i> has no limit for the <i>path</i> or file descriptor, both <i>pathconf</i>() and
<i>fpathconf</i>() shall return -1 without changing <i>errno</i>. If the implementation needs to use <i>path</i> to determine the
value of <i>name</i> and the implementation does not support the association of <i>name</i> with the file specified by <i>path</i>,
or if the process did not have appropriate privileges to query the file specified by <i>path</i>, or <i>path</i> does not exist,
<i>pathconf</i>() shall return -1 and set <i>errno</i> to indicate the error.</p>

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

<p>Otherwise, <i>pathconf</i>() or <i>fpathconf</i>() shall return the current variable value for the file or directory without
changing <i>errno</i>. The value returned shall not be more restrictive than the corresponding value available to the application
when it was compiled with the implementation's <a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a> or <a href=
"../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>.</p>
</blockquote>

<h4><a name="tag_03_178_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>pathconf</i>() function shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The value of <i>name</i> is not valid.</dd>

<dt>[ELOOP]</dt>

<dd>A loop exists in symbolic links encountered during resolution of the <i>path</i> argument.</dd>
</dl>

<p>The <i>pathconf</i>() function may fail if:</p>

<dl compact>
<dt>[EACCES]</dt>

<dd>Search permission is denied for a component of the path prefix.</dd>

<dt>[EINVAL]</dt>

<dd>The implementation does not support an association of the variable <i>name</i> with the specified file.</dd>

<dt>[ELOOP]</dt>

<dd>More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the <i>path</i> argument.</dd>

<dt>[ENAMETOOLONG]</dt>

<dd>
The length of the <i>path</i> argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.</dd>

<dt>[ENAMETOOLONG]</dt>

<dd>
As a result of encountering a symbolic link in resolution of the <i>path</i> argument, the length of the substituted pathname
string exceeded {PATH_MAX}.</dd>

<dt>[ENOENT]</dt>

<dd>A component of <i>path</i> does not name an existing file or <i>path</i> is an empty string.</dd>

<dt>[ENOTDIR]</dt>

<dd>A component of the path prefix is not a directory.</dd>
</dl>

<p>The <i>fpathconf</i>() function shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The value of <i>name</i> is not valid.</dd>
</dl>

<p>The <i>fpathconf</i>() function may fail if:</p>

<dl compact>
<dt>[EBADF]</dt>

<dd>The <i>fildes</i> argument is not a valid file descriptor.</dd>

<dt>[EINVAL]</dt>

<dd>The implementation does not support an association of the variable <i>name</i> with the specified file.</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_178_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_178_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_178_08"></a>RATIONALE</h4>

<blockquote>
<p>The <i>pathconf</i>() function was proposed immediately after the <a href="../functions/sysconf.html"><i>sysconf</i>()</a>
function when it was realized that some configurable values may differ across file system, directory, or device boundaries.</p>

<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 <a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a> on such a
system.</p>

<p>Therefore, various useful values can be queried on any pathname or file descriptor, assuming that the appropriate permissions
are in place.</p>

<p>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.</p>

<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 <a href="../functions/chown.html"><i>chown</i>()</a> function and look for an error in case it
happens.)</p>

<p>Unlike the values returned by <a href="../functions/sysconf.html"><i>sysconf</i>()</a>, 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 <i>pathconf</i>(), the file system in question may have been unmounted and remounted with different characteristics.</p>

<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 <i>path</i> or <i>fildes</i> 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 <i>name</i> is not valid for that variable.</p>

<p>If the value of any of the limits is unspecified (logically infinite), they will not be defined in <a href=
"../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a> and the <i>pathconf</i>() and <i>fpathconf</i>() functions return -1
without changing <i>errno</i>. This can be distinguished from the case of giving an unrecognized <i>name</i> argument because
<i>errno</i> is set to [EINVAL] in this case.</p>

<p>Since -1 is a valid return value for the <i>pathconf</i>() and <i>fpathconf</i>() functions, applications should set
<i>errno</i> to zero before calling them and check <i>errno</i> only if the return value is -1.</p>

<p>For the case of {SYMLINK_MAX}, since both <i>pathconf</i>() and <a href="../functions/open.html"><i>open</i>()</a> follow
symbolic links, there is no way that <i>path</i> or <i>fildes</i> could refer to a symbolic link.</p>
</blockquote>

<h4><a name="tag_03_178_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_178_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="confstr.html"><i>confstr</i>()</a> , <a href="sysconf.html"><i>sysconf</i>()</a> , the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a>, <a href=
"../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>, the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001</p>
</blockquote>

<h4><a name="tag_03_178_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 3. Included for alignment with the POSIX.1-1988 standard.</p>
</blockquote>

<h4><a name="tag_03_178_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension.</p>

<p>Large File Summit extensions are added.</p>
</blockquote>

<h4><a name="tag_03_178_13"></a>Issue 6</h4>

<blockquote>
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The DESCRIPTION is updated to include {FILESIZEBITS}.</p>
</li>

<li>
<p>The [ELOOP] mandatory error condition is added.</p>
</li>

<li>
<p>A second [ENAMETOOLONG] is added as an optional error condition.</p>
</li>
</ul>

<p>The following changes were made to align with the IEEE&nbsp;P1003.1a draft standard:</p>

<ul>
<li>
<p>The _PC_SYMLINK_MAX entry is added to the table in the DESCRIPTION.</p>
</li>
</ul>

<p>The following <i>pathconf</i>() variables and their associated names are added for alignment with
IEEE&nbsp;Std&nbsp;1003.1d-1999:</p>

<blockquote>
<pre>
{POSIX_ALLOC_SIZE_MIN}
{POSIX_REC_INCR_XFER_SIZE}
{POSIX_REC_MAX_XFER_SIZE}
{POSIX_REC_MIN_XFER_SIZE}
{POSIX_REC_XFER_ALIGN}
</pre>
</blockquote>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/18 is applied, changing the fourth paragraph of the DESCRIPTION and
removing shading and margin markers from the table. This change is needed since implementations are required to support all of
these symbols.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>