friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/pathconf.htm

690 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>pathconf()--Get Configurable Path Name Variables</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 010402 JTROUS Changes for PASE, V4R2, XPF DCR 98391 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 0205?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 050404 JTROUS: fix enums, no change flag, V5R4 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>pathconf()--Get Configurable Path Name Variables</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
long pathconf(const char <em>*path</em>, int <em>name</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>pathconf()</strong> function lets an application determine the
value of a configuration variable (<em>name</em>) associated with a particular
file or directory (<em>path</em>).</p>
<p>If the named file is a symbolic link, <strong>pathconf()</strong> resolves
the symbolic link.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>path</em></strong></dt>
<dd>(Input) A pointer to the null-terminated path name of the file for which
the value of the configuration variable is requested.
<p>This parameter is assumed to be represented in the CCSID (coded character
set identifier) currently in effect for the process. If the CCSID of the job is
65535, this parameter is assumed to be represented in the default CCSID of the
job.</p>
<p>See <a href="pathconfu.htm">QlgPathconf()--Get Configurable Path Name
Variables</a> for a description and an example of supplying the <em>path</em>
in any CCSID.</p>
<br>
</dd>
<dt><strong><em>name</em></strong></dt>
<dd>(Input) The name of the configuration variable value requested.</dd>
</dl>
<p>The value of <em>name</em> can be any one of the following set of symbols
defined in the &lt;<strong>unistd.h</strong>&gt; header file, each standing for
a configuration variable:</p>
<dl compact>
<dt><em>_PC_LINK_MAX</em></dt>
<dd>
<p>Represents LINK_MAX, which indicates the maximum number of links the file
can have. If <em>path</em> is a directory, <strong>pathconf()</strong> returns
the maximum number of links that can be established to the directory
itself.</p>
</dd>
<dt><em>_PC_MAX_CANON</em></dt>
<dd>
<p>Represents MAX_CANON, which indicates the maximum number of bytes in a
terminal canonical input line.</p>
</dd>
<dt><em>_PC_MAX_INPUT</em></dt>
<dd>
<p>Represents MAX_INPUT, which indicates the minimum number of bytes for which
space is available in a terminal input queue. This available space is the
maximum number of bytes that a portable application can have the user enter
before the application actually reads the input.</p>
</dd>
<dt><em>_PC_NAME_MAX</em></dt>
<dd>
<p>Represents NAME_MAX, which indicates the maximum number of bytes in a file
name (not including any terminating null at the end if the file name is stored
as a string). This symbol refers only to the file name itself; that is, the
last component of the path name of the file. <strong>pathconf()</strong>
returns the maximum length of file names, even when the path does not refer to
a directory.</p>
<p>This value is the number of bytes allowed in the file name if it were
encoded in the CCSID of the job. If the CCSID is mixed, this number is an
estimate and may be larger than the actual allowable maximum.</p>
</dd>
<dt><em>_PC_PATH_MAX</em></dt>
<dd>
<p>Represents PATH_MAX, which indicates the maximum number of bytes in a
complete path name (not including any terminating null at the end if the path
name is stored as a string). <strong>pathconf()</strong> returns the maximum
length of a relative path name relative to <em>path</em>, even when <em>
path</em> does not refer to a directory.</p>
<p>This value is the number of bytes allowed in the path name if it were
encoded in the CCSID of the job. If the CCSID is mixed, this number is an
estimate and may be larger than the actual allowable maximum.</p>
</dd>
<dt><em>_PC_PIPE_BUF</em></dt>
<dd>
<p>Represents PIPE_BUF, which indicates the maximum number of bytes that can be
written "atomically" to a pipe. If more than this number of bytes are written
to a pipe, the operation may take more than one physical write operation and
physical read operation to read the data on the other end of the pipe. If <em>
path</em> is a FIFO special file, <strong>pathconf()</strong> returns the value
for the file itself. If <em>path</em> is a directory, <strong>
pathconf()</strong> returns the value for any FIFOs that exist or that can be
created under the directory. If <em>path</em> is any other kind of file, an
error of [EINVAL] is returned.</p>
</dd>
<dt><em>_PC_CHOWN_RESTRICTED</em></dt>
<dd>
<p>Represents _POSIX_CHOWN_RESTRICTED, as defined in the
&lt;<strong>unistd.h</strong>&gt; header file. It restricts use of <strong>
chown()</strong> to a job with appropriate privileges, and allows the group ID
of a file to be changed only to the effective group ID of the job or to one of
its supplementary group IDs. If <em>path</em> is a directory, <strong>
pathconf()</strong> returns the value for any kind of file under the directory,
but not for subdirectories of the directory.</p>
</dd>
<dt><em>_PC_NO_TRUNC</em></dt>
<dd>
<p>Represents _POSIX_NO_TRUNC, as defined in the
&lt;<strong>unistd.h</strong>&gt; header file. It generates an error if a file
name is longer than NAME_MAX. If <em>path</em> refers to a directory, the value
returned by <strong>pathconf()</strong> applies to all files under that
directory.</p>
</dd>
<dt><em>_PC_VDISABLE</em></dt>
<dd>
<p>Represents _POSIX_VDISABLE, as defined in the
&lt;<strong>unistd.h</strong>&gt; header file. This symbol indicates that
terminal special characters can be disabled using this character value, if it
is defined.</p>
</dd>
<dt><em>_PC_THREAD_SAFE</em></dt>
<dd>
<p>This symbol is used to determine if the object represented by <em>path</em>
resides in a threadsafe file system. <strong>pathconf()</strong> returns the
value 1 if the file system is threadsafe and 0 if the file system is not
threadsafe. <strong>fpathconf()</strong> will never fail with error code
[ENOTSAFE] when called with _PC_THREAD_SAFE.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<p><strong><a name="TBLAPATHCO">Authorization required for
pathconf()</a></strong></p>
<table border cellpadding="5" width="80%">
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="center" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="75%">Each directory in the path name
preceding the object</td>
<td align="center" valign="top" width="15%">*X</td>
<td align="left" valign="top" width="10%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top" width="99%">Object</td>
<td align="center" valign="top" width="1%">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>value</em></dt>
<dd><strong>pathconf()</strong> was successful. The value of the variable
requested in <em>name</em> is returned.</dd>
<dt><em>-1</em></dt>
<dd>One of the following has occurred:<br>
<br>
<ul>
<li>A particular variable has no limit (for example, _PC_PATH_MAX). The <em>
errno</em> global variable is not changed.</li>
<li><strong>pathconf()</strong> was not successful. The <em>errno</em> is
set.</li>
</ul>
</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>fpathconf()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONVERT">ECONVERT</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFILECVT">EFILECVT</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
<p>For example, <em>name</em> is not
a valid configuration variable name, or the given variable cannot be associated
with the specified file.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EISDIR">EISDIR</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EPERM">EPERM</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROOBJ">EROOBJ</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
</tr>
</table>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could indicate one of the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EADDRNOTAVAIL">EADDRNOTAVAIL</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<ol type="1">
<li>When this function is called with any configuration variable name except
_PC_THREAD_SAFE, the following usage note applies:<br>
<br>
<ul>
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>unistd.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
</li>
<li><a href="chown.htm">chown()</a>--Change Owner and Group of File<br>
</li>
<li><a href="fpathcon.htm">fpathconf()</a>--Get Configurable Path Name
Variables by Descriptor<br>
</li>
<li><a href="pathconfu.htm">QlgPathconf()</a>--Get Configurable Path Name
Variables</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example determines the maximum number of bytes in a file
name:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;errno.h&gt;
main() {
long result;
errno = 0;
puts("examining NAME_MAX limit for root filesystem");
if ((result = pathconf("/", _PC_NAME_MAX)) == -1)
if (errno == 0)
puts("There is no limit to NAME_MAX.");
else perror("pathconf() error");
else
printf("NAME_MAX is %ld\n", result);
}
</pre>
<p><strong>Output:</strong></p>
<pre>
examining NAME_MAX limit for root filesystem
NAME_MAX is 255
</pre>
<br>
<hr>
API introduced: V3R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink