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/stat.htm

1118 lines
29 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>stat()--Get File Information</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. -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- 010405 JTROUS Add new field descriptions dev64 etc,V5R2,98391 -->
<!-- 010503 JTROUS Add new field desc nlink32, V5R2a, 98761 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020516 JTROUS Fix typo on fstat64 reference, V5R3 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 020624 RTHEIS: Add fclear() and fclear64(), V5R3 -->
<!-- 0206?? JET : This file has undergone html cleanup -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 021021 VONBERGE: Add new qsys.lib usrprf auth reqs. D99381.1 -->
<!-- 021107 JTROUS Add desc to blksize,allocsize, V5R3 -->
<!-- 040206 TIMCLARK: Update stat structure with st_vfs, V5R4 -->
<!-- 040525 TIMCLARK: Add usage note about QFileSvr.400 and st_vfs -->
<!-- 040721 JTROUS: fix OS/400 reference, no change flag, V5R4 -->
<!-- 050407 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>stat()--Get File Information</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/stat.h&gt;
int stat(const char <em>*path</em>, struct stat <em>*buf</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="#HDRSTAUSAG">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>stat()</strong> function gets status information about a
specified file and places it in the area of memory pointed to by the <em>
buf</em> argument.</p>
<p>If the named file is a symbolic link, <strong>stat()</strong> resolves the
symbolic link. It also returns information about the resulting file.</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 from which
information is required.
<p>This parameter is assumed to be represented in the CCSID (coded character
set identifier) currently in effect for the job. 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="statu.htm">QlgStat()--Get File Information (using NLS-enabled
path name)</a> for a description and an example of supplying the <em>path</em>
in any CCSID.</p>
<br>
</dd>
<dt><strong><em>buf</em></strong></dt>
<dd>(Output) A pointer to the area to which the information should be
written.</dd>
</dl>
<p>The information is returned in the following <samp>stat</samp> structure, as
defined in the &lt;<strong>sys/stat.h</strong>&gt; header file:</p>
<table border>
<tr>
<td align="left" valign="top" width="15%">mode_t</td>
<td align="left" valign="top" width="20%">st_mode</td>
<td align="left" valign="top" width="75%">A bit string indicating the
permissions and privileges of the file. Symbols are defined in the
&lt;sys/stat.h&gt; header file to refer to bits in a mode_t value; these
symbols are listed in <a href="chmod.htm">chmod()--Change File
Authorizations</a>.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">ino_t</td>
<td align="left" valign="top">st_ino</td>
<td align="left" valign="top">The file ID for the object. This number uniquely
identifies the object within a file system. When st_ino and st_dev are used
together, they uniquely identify the object on the system.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">nlink_t</td>
<td align="left" valign="top">st_nlink</td>
<td align="left" valign="top">The number of links to the file. This field will
be 65,535 if the value could not fit in the specified nlink_t field. The
complete value will be in the st_nlink32 field.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned short</td>
<td align="left" valign="top">st_reserved2</td>
<td align="left" valign="top">Reserved.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">uid_t</td>
<td align="left" valign="top">st_uid</td>
<td align="left" valign="top">The numeric user ID (uid) of the owner of the
file.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">gid_t</td>
<td align="left" valign="top">st_gid</td>
<td align="left" valign="top">The numeric group ID (gid) for the file.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">off_t</td>
<td align="left" valign="top">st_size</td>
<td align="left" valign="top">Defined as follows for each file type:
<dl>
<dt><em>Regular File</em></dt>
<dd>The number of data bytes in the file.</dd>
<dt><em>Directory</em></dt>
<dd>The number of bytes allocated to the directory.</dd>
<dt><em>Symbolic Link</em></dt>
<dd>The number of bytes in the path name stored in the symbolic link.</dd>
<dt><em>Local Socket</em></dt>
<dd>Always zero.</dd>
<dt><em>Operating System Native Object</em></dt>
<dd>This value is dependent on the object type.</dd>
</dl>
</td>
</tr>
<tr>
<td align="left" valign="top">time_t</td>
<td align="left" valign="top">st_atime</td>
<td align="left" valign="top">The most recent time the file was accessed.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">time_t</td>
<td align="left" valign="top">st_mtime</td>
<td align="left" valign="top">The most recent time the contents of the file
were changed.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">time_t</td>
<td align="left" valign="top">st_ctime</td>
<td align="left" valign="top">The most recent time the status of the file was
changed.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">dev_t</td>
<td align="left" valign="top">st_dev</td>
<td align="left" valign="top">The file system ID to which the object belongs.
This number uniquely identifies the file system to which the object belongs.
When st_ino and st_dev are used together, they uniquely identify the object on
the system. This field will be 4,294,967,295 if the value could not fit in the
specified dev_t field. The complete value will be in the st_dev64 field.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">size_t</td>
<td align="left" valign="top">st_blksize</td>
<td align="left" valign="top">The block size of the file in bytes.
This number is the number of bytes in a block of disk unit storage.
<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned long</td>
<td align="left" valign="top">st_allocsize</td>
<td align="left" valign="top">The number of bytes allocated to the file.
The allocated size varies by object type and file system. For example, the
allocated size includes the object data size as shown in st_size as well as any
logically sized extents to accomodate anticipated future requirements for
the object data. It may or may not include additional bytes for attribute
information.
<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">qp0l_objtype_t</td>
<td align="left" valign="top">st_objtype</td>
<td align="left" valign="top">The object type; for example, *STMF or
*DIR. Refer to <a href="../rbam6/clpro.htm">CL Programming</a> topic for a list of the
object types.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned short</td>
<td align="left" valign="top">st_codepage</td>
<td align="left" valign="top">The code page derived from the CCSID used for the
data in the file or the extended attributes of the directory. If the returned
value of this field is zero (0), there is more than one code page associated
with the st_ccsid. If the st_ccsid is not a supported CCSID, the
st_codepage is set equal to the st_ccsid.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned short</td>
<td align="left" valign="top">st_ccsid</td>
<td align="left" valign="top">The CCSID used for the data in the file or the
extended attributes of the directory.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">dev_t</td>
<td align="left" valign="top">st_rdev</td>
<td align="left" valign="top">The device ID of the object if the object is a
character special file or block special file. This number uniquely identifies
the file device. This field will be 4,294,967,295 if the value could not fit in
the specified dev_t field. The complete value will be in the st_rdev64
field.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">nlink32_t</td>
<td align="left" valign="top">st_nlink32</td>
<td align="left" valign="top">The number of links to the file.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">dev64_t</td>
<td align="left" valign="top">st_rdev64</td>
<td align="left" valign="top">The device ID of the object in 64 bit format. See
st_rdev for more information.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">dev64_t</td>
<td align="left" valign="top">st_dev64</td>
<td align="left" valign="top">The file system ID to which the object belongs in
64 bit format. See st_dev for more information.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">unsigned int</td>
<td align="left" valign="top">st_vfs</td>
<td align="left" valign="top">The unique mount ID of the file system on which
the object is located. Information about each mounted file system can be
obtained by using the QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS option of
<A href="qp0lflop.htm">QP0LFLOP()--Perform file system operation</A>.
<br> Unlike st_dev and st_dev64, st_vfs identifies a particular instance of a file system.
For any single file system, st_dev and st_dev64 will remain the
same across multiple mounts. In contrast, st_vfs is incremented whenever a file
system is mounted and is different for each mount of a file system.
Therefore, the value of st_vfs may change due to any system processing which
unmounts and mounts file systems, such as IPL and Reclaim Storage (RCLSTG).
<img src="deltaend.gif" alt="End of change">
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">st_reserved1[32]<img src="deltaend.gif" alt="End of change"></td>
<td align="left" valign="top">Reserved.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned int</td>
<td align="left" valign="top">st_ino_gen_id</td>
<td align="left" valign="top">The generation ID associated with the file
ID.</td>
</tr>
</table>
<p>Values of <samp>time_t</samp> are given in terms of seconds since a fixed
point in time called the <em>Epoch</em>.</p>
<p>You can examine properties of a <samp>mode_t</samp> value from the <samp>
st_mode</samp> field using a collection of macros defined in the <strong>
&lt;sys/stat.h&gt;</strong> header file. If <em>mode</em> is a <samp>
mode_t</samp> value, then:</p>
<dl compact>
<dt><em>S_ISBLK(mode)</em></dt>
<dd>Is nonzero for block special files</dd>
<dt><em>S_ISCHR(mode)</em></dt>
<dd>Is nonzero for character special files</dd>
<dt><em>S_ISDIR(mode)</em></dt>
<dd>Is nonzero for directories</dd>
<dt><em>S_ISFIFO(mode)</em></dt>
<dd>Is nonzero for pipes and FIFO special files</dd>
<dt><em>S_ISREG(mode)</em></dt>
<dd>Is nonzero for regular files</dd>
<dt><em>S_ISLNK(mode)</em></dt>
<dd>Is nonzero for symbolic links</dd>
<dt><em>S_ISSOCK(mode)</em></dt>
<dd>Is nonzero for local sockets</dd>
<dt><em>S_ISNATIVE(mode)</em></dt>
<dd>Is nonzero for operating system native objects</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<strong><a name="TBLASTAT">Authorization Required for stat()</a></strong>
<table border width="100%">
<!-- cols="45 25 30" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top">Each directory in the path name preceding the
object</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object, if object type is not *USRPRF</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
<tr>
<td align="left" valign="top">Object, if object type is *USRPRF</td>
<td align="left" valign="top">Any authority greater than *EXCLUDE</td>
<td align="left" valign="top">ENOENT</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>stat()</strong> was successful. The information is returned in <em>
buf</em>.</dd>
<dt><em>-1</em></dt>
<dd><strong>stat()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3><a name="HDRSTAERRS">Error Conditions</a></h3>
<p>If <strong>stat()</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 align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONVERT">ECONVERT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFILECVT">EFILECVT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EOVERFLOW">EOVERFLOW</a>]</em></td>
<td align="left" valign="top">
<p>The file size in bytes cannot be represented correctly in the structure
pointed to by buf (the file is larger than 2GB minus 1 byte).</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EPERM">EPERM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROOBJ">EROOBJ</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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>
<td align="left" valign="top">
&nbsp;
</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 align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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 align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<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>
<br>
<h3><a name="HDRSTAUSAG">Usage Notes</a></h3>
<ol type="1">
<li>This function will fail with error code [ENOTSAFE] when both of the
following conditions occur:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:
<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>
<br>
</li>
<li>
"Root" (/), QOpenSys, and User-Defined File System Differences
<p>The st_allocsize value can be influenced by
the setting of the disk storage option attribute. See
<a href="qsetattr.htm">Qp0lSetAttr()--Set Attributes</a> for more
information.
</p></li>
<li>QSYS.LIB and Independent ASP QSYS.LIB File System Differences
<p>The <strong>stat()</strong> function could return zero for the <samp>
st_atime</samp> value (in the <samp>stat</samp> structure) under some
conditions.</p>
</li>
<li>QDLS File System Differences
<p>If the date corresponding to the <samp>st_atime</samp>, <samp>
st_mtime</samp>, or <samp>st_ctime</samp> value precedes 1970, <strong>
stat()</strong> returns zero for that value. Also, if the specified <em>
path</em> is /QDLS, <strong>stat()</strong> returns zero for all three values
<samp>st_atime</samp>, <samp>st_mtime</samp>, and <samp>st_ctime</samp>.</p>
</li>
<li>QOPT File System Differences<br>
<p>The value for st_atime will always be zero. The value for st_ctime will
always be the creation date and time of the file or directory.</p>
<p>The user, group, and other mode bits are always on for an object that exists
on a volume not formatted in Universal Disk Format (UDF).</p>
<p>If the object exists on a volume formatted in Universal Disk Format (UDF),
the authorization that is checked for the object and preceding directories in
the path name follows the rules described in <a href="#TBLASTAT">Authorization
Required for stat()</a>, "." If the object exists on a volume formatted in some
other media format, no authorization checks are made on the object or on each
directory in the path name. The volume authorization list is checked for *USE
authority regardless of the media format of the volume.</p>
<p><strong>stat()</strong> on /QOPT will always return 2,147,483,647 for size fields.</p>
<p><strong>stat()</strong> on optical volumes will return the volume capacity or 2,147,483,647,
whichever is smaller.</p>
<p>The file access time is not changed.</p>
</li>
<li>Network File System Differences
<p>Local access to remote files through the Network File System may produce
unexpected results due to conditions at the server. Once a file is open,
subsequent requests to perform operations on the file can fail because file
attributes are checked at the server on each request. If permissions on the
file are made more restrictive at the server or the file is unlinked or made
unavailable by the server for another client, your operation on an open file
descriptor will fail when the local Network File System receives these updates.
The local Network File System also impacts operations that retrieve file
attributes. Recent changes at the server may not be available at your client
yet, and old values may be returned from operations. (Several options on the
Add Mounted File System (ADDMFS) command determine the time between refresh
operations of local data.)</p>
</li>
<li>QNetWare File System Differences
<p>The QNetWare file system does not fully support mode bits. See <a href=
"../rzaef/rzaefoverview.htm">NetWare on iSeries</a> for more information.</p>
</li>
<li><img src="delta.gif" alt="Start of change">
QFileSvr.400 File System Differences
<p>The value of st_vfs will always be 0 for remote objects accessed via
QFileSvr.400.<img src="deltaend.gif" alt="End of change"></p>
</li>
<li>This function will fail with the [EOVERFLOW] error if the file size in
bytes cannot be represented correctly in the structure pointed to by buf (the
file is larger than 2GB minus 1 byte).<br>
<br>
</li>
<li>When you develop in C-based languages and this function is compiled with
_LARGE_FILES defined, it will be mapped to <a href="stat64.htm">stat64()</a>.
Note that the type of the buf parameter, <samp>struct stat *</samp>, also will
be mapped to type <samp>struct stat64 *</samp>.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/stat.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li>The &lt;<strong>sys/types.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li><a href="chmod.htm">chmod()</a>--Change File Authorizations</li>
<li><a href="chown.htm">chown()</a>--Change Owner and Group of File</li>
<li><a href="creat.htm">creat()</a>--Create or Rewrite File</li>
<li><a href="dup.htm">dup()</a>--Duplicate Open File Descriptor</li>
<li>
<a href="fclear.htm">fclear()</a>--Write (Binary Zeros) to Descriptor
</li>
<li><a href="fclear64.htm">fclear64()</a>--Write (Binary Zeros) to Descriptor
(Large File Enabled)
</li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command</li>
<li><a href="fstat.htm">fstat()</a>--Get File Information by Descriptor</li>
<li><a href="link.htm">link()</a>--Create Link to File</li>
<li><a href="lstat.htm">lstat()</a>--Get File or Link Information</li>
<li><a href="mkdir.htm">mkdir()</a>--Make Directory</li>
<li><a href="open.htm">open()</a>--Open File</li>
<li><a href="statu.htm">QlgStat()</a>--Get File Information (using NLS-enabled
path name)</li>
<li><img src="delta.gif" alt="Start of change"><a href="qp0lflop.htm">QP0LFLOP()</a>--Perform file system operation<img src="deltaend.gif" alt="End of change"></li>
<li><a href="read.htm">read()</a>--Read from Descriptor</li>
<li><a href="readlink.htm">readlink()</a>--Read Value of Symbolic Link</li>
<li><a href="stat64.htm">stat64()</a>--Get File Information (Large File
Enabled)</li>
<li><a href="symlink.htm">symlink()</a>--Make Symbolic Link</li>
<li><a href="unlink.htm">unlink()</a>--Remove Link to File</li>
<li><a href="utime.htm">utime()</a>--Set File Access and Modification
Times</li>
<li><a href="write.htm">write()</a>--Write to Descriptor</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 gets status information about a file:</p>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;stdio.h&gt;
#include &lt;time.h&gt;
main() {
struct stat info;
if (stat("/", &amp;info) != 0)
perror("stat() error");
else {
puts("stat() returned the following information about root f/s:");
printf(" inode: %d\n", (int) info.st_ino);
printf(" dev id: %d\n", (int) info.st_dev);
printf(" mode: %08x\n", info.st_mode);
printf(" links: %d\n", info.st_nlink);
printf(" uid: %d\n", (int) info.st_uid);
printf(" gid: %d\n", (int) info.st_gid);
}
}
</pre>
<p>Output: note that the following information will vary from system to
system.</p>
<pre>
stat() returned the following information about root f/s:
inode: 0
dev id: 1
mode: 010001ed
links: 3
uid: 137
gid: 500
</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 Copy Permalink