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

698 lines
18 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>fstat()--Get File Information by Descriptor</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 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- IFS and Sockets versions merged for V5R2 -->
<!-- Edited by Kersten Feb 02 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 020618 EMIG Updates for NFS threadsafety, V5R3 -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 040218 TIMCLARK: Add usage note about st_vfs. -->
<!-- 040525 TIMCLARK: Add usage note about QFileSvr.400 and st_vfs.-->
<!-- 050328 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>fstat()--Get File Information by Descriptor</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/stat.h&gt;
int fstat(int <em>descriptor</em>,
struct stat *<em>buffer</em>)
</pre>
<br>
&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="#unotes">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>fstat()</strong> function gets status information about the
object specified by the open descriptor <em>descriptor</em> and stores the
information in the area of memory indicated by the <em>buffer</em> argument.
The status information is returned in a <samp>stat</samp> structure, as defined
in the &lt;<strong>sys/stat.h</strong>&gt; header file.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>descriptor</strong></dt>
<dd>(Input) The descriptor for which information is to be retrieved.<br>
<br>
</dd>
<dt><strong>buffer</strong></dt>
<dd>(Output) A pointer to a buffer of type <strong>struct stat</strong> in
which the information is returned. The structure pointed to by the <em>
buffer</em> parameter is described in <a href="stat.htm">stat()-- Get File
Information</a>.
<p>The <em>st_mode</em>, <em>st_dev</em>, and <em>st_blksize</em> fields are
the only fields set for socket descriptors. The <em>st_mode</em> field is set
to a value that indicates the descriptor is a socket descriptor, the <em>
st_dev</em> field is set to -1, and the <em>st_blksize</em> field is set to an
optimal value determined by the system.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top"><strong>fstat()</strong> was successful. The
information is returned in <em>buffer</em>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>fstat()</strong> was not successful. The
<em>errno</em> global variable is set to indicate the error.</td>
</tr>
</table>
<br>
<h3>Error Conditions</h3>
<p>If <strong>fstat()</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#EBADF">EBADF</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#EBADFUNC">EBADFUNC</a>]</em></td>
<td align="left" valign="top">
<p>A given descriptor or directory pointer is not valid for this operation. The
specified descriptor is incorrect, or does not refer to an open object.</p>
</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#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#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
<p>This error code may be returned when the underlying object represented by
the descriptor is unable to fill the <strong>stat</strong> structure (for
example, if the function was issued against a socket descriptor that had its
connection reset).</p>
</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#ENOBUFS">ENOBUFS</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSYSRSC">ENOSYSRSC</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#ENOTSAFE">ENOTSAFE</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 specified file exists and its size is too large to be represented in the
structure pointed to by <em>buffer</em> (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#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#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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 also 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#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td valign="top" width="15%">CPFA0D4 E</td>
<td valign="top" width="85%">File system error occurred. Error number
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA081 E</td>
<td align="left" valign="top">Unable to set return value or error code.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3418 E</td>
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" 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="unotes">Usage Notes</a></h3>
<ol>
<li>This function will fail with error code [ENOTSAFE] when both of the
following conditions occur:
<ul>
<li>Where multiple threads exist in the job.<br>
<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>Sockets-Specific Notes
<ul>
<li>The field <em>st_mode</em> can be inspected using the S_ISSOCK macro
(defined in <strong>&lt;sys/stat.h&gt;</strong>) to determine if the descriptor
is pointing to a socket descriptor.<br>
<br>
</li>
<li>For socket descriptors, use the send buffer size (this is the value
returned for <em>st_blksize</em>) for the length parameter on your input and
output functions. This can improve performance.
<p><strong>Note:</strong> IBM reserves the right to change the calculation of
the optimal send size.</p>
</li>
</ul>
</li>
<li>QOPT File System Differences
<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><strong>fstat()</strong> on /QOPT will always return 2,147,483,647 for size fields.</p>
<p><strong>fstat()</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
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 the <a href=
"../rzaef/rzaefoverview.htm">Netware on iSeries</a> topic 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 specified file
exists and its size is too large to be represented in the structure pointed to
by <em>buffer</em> (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 <strong>fstat64()</strong>. Note
that the type of the <em>buffer</em> parameter, <samp>struct stat *</samp>,
also will be mapped to type <samp>struct stat64 *</samp>. See <a href=
"stat64.htm">stat64()</a> for more information on this structure.<br><br></li>
<li><img src="delta.gif" alt="Start of change">If a descriptor for a pipe or socket is passed to this
function, the value of st_vfs will be 0. Therefore, information about these
objects' corresponding file system cannot be obtained using the
QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS option of <a href="qp0lflop.htm">
QP0LFLOP()--Perform file system operation</a>.
<img alt="End of change" src="deltaend.gif">
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/types.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)
</li>
<li>The &lt;<strong>sys/stat.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)
</li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command
</li>
<li><a href="fstat64.htm">fstat64()</a>--Get File Information by Descriptor
(Large File Enabled)
</li>
<li><a href="lstat.htm">lstat()</a>--Get File or Link Information
</li>
<li><a href="open.htm">open()</a>--Open File
</li>
<li><a href="socket.htm">socket()</a>--Create Socket
</li>
<li><a href="stat.htm">stat()</a>--Get File Information
</li>
<li><a href="stat64.htm">stat64()</a>--Get File Information (Large File
Enabled)</li>
<li><img src="delta.gif" alt="Start of change">
<a href="qp0lflop.htm">QP0LFLOP()</a>--Perform file system operation<img alt="End of change" src="deltaend.gif"></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:</p>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;stdio.h&gt;
#include &lt;time.h&gt;
main() {
char fn[]="temp.file";
struct stat info;
int file_descriptor;
if ((file_descriptor = creat(fn, S_IWUSR)) &lt; 0)
perror("creat() error");
else {
if (fstat(file_descriptor, &amp;info) != 0)
perror("fstat() error");
else {
puts("fstat() returned:");
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);
}
close(file_descriptor);
unlink(fn);
}
}
</pre>
<p><strong>Output:</strong> Note that the output may vary from system to
system.</p>
<pre>
fstat() returned:
inode: 3057
dev id: 1
mode: 03000080
links: 1
uid: 137
gid: 500
</pre>
<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