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

718 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>fstatvfs()--Get File System 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. -->
<!-- file cleaned -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020514 JET This file has undergone html cleanup -->
<!-- 020618 EMIG Updates for NFS threadsafety, V5R3 -->
<!-- 020708 RTHEIS Add fclear() and fclear64(), V5R3 -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 040211 JTROUS Remove authority information, N/A, V5R4 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--End Header Records --><!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>fstatvfs()--Get File System Information by Descriptor</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/statvfs.h&gt;
int fstatvfs(int <em>fildes</em>, struct statvfs <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="#HDRFSTVUSG">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>fstatvfs()</strong> function gets status information about the
file system that contains the file referenced by the open file descriptor <em>
fildes</em>. The information is stored in the area of memory indicated by the
<em>buf</em> argument. The status information is returned in a <samp>
statvfs</samp> structure, as defined in the
&lt;<strong>sys/statvfs.h</strong>&gt; header file.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>fildes</em></strong></dt>
<dd>(Input) The file descriptor of the file from which file system information
is required.<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 elements of the <samp>statvfs</samp> structure are described in <a href=
"statvfs.htm">statvfs()--Get File System Information</a>. Signed fields of the
<samp>statvfs</samp> structure that are not supported by the mounted file
system will be set to -1.</p>
<p><a name="HDRFSTVAUT"><strong>Authorities</strong></a></p>
<p><img src="delta.gif" alt="Start of change">
No authorization is required.
<img src="deltaend.gif" alt="End of change">
</p>
<br>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>fstatvfs()</strong> was successful. The information is returned in
<em>buf</em>.</dd>
<dt><em>-1</em></dt>
<dd><strong>fstatvfs()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3 id="HDRFSTVERR">Error Conditions</h3>
<p>If <strong>fstatvfs()</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#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#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#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%">
<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="HDRFSTVUSG">Usage Notes</a></h3>
<ol type="1">
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
<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:
<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" (/) and QOpenSys File System Differences
<p>These file systems return the <samp>f_flag</samp> field with the <samp>
ST_NOSUID</samp> flag bit turned off. However, support for the setuid/setgid
semantics is limited to the ability to store and retrieve the <samp>
S_ISUID</samp> and <samp>S_ISGID</samp> flags when these file systems are
accessed from the Network File System server.</p>
<br>
</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>
<br>
</li>
<li>When you develop in C-based languages and an application is compiled with
the <samp>_LARGE_FILES</samp> macro defined, the <strong>fstatvfs()</strong>
API will be mapped to a call to the <strong>fstatvfs64()</strong>.
Additionally, the <samp>struct statvfs</samp> data type will be mapped to a
<samp>struct statvfs64</samp>.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/statvfs.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)<br>
</li>
<li>The &lt;<strong>sys/types.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)<br>
</li>
<li><a href="chmod.htm">chmod()</a>--Change File Authorizations<br>
</li>
<li><a href="chown.htm">chown()</a>--Change Owner and Group of File<br>
</li>
<li><a href="creat.htm">creat()</a>--Create or Rewrite File<br>
</li>
<li><a href="dup.htm">dup()</a>--Duplicate Open File Descriptor<br>
</li>
<li>
<a href="fclear.htm">fclear()</a>--Write (Binary Zeros) to Descriptor<br>
</li>
<li><a href="fclear64.htm">fclear64()</a>--Write (Binary Zeros) to Descriptor (Large File Enabled)
<br></li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br>
</li>
<li><a href="fstatv64.htm">fstatvfs64()</a>--Get File System Information by
Descriptor (64-Bit Enabled)<br>
</li>
<li><a href="link.htm">link()</a>--Create Link to File<br>
</li>
<li><a href="open.htm">open()</a>--Open File<br>
</li>
<li><a href="read.htm">read()</a>--Read from Descriptor<br>
</li>
<li><a href="statvfs.htm">statvfs()</a>--Get File System Information<br>
</li>
<li><a href="unlink.htm">unlink()</a>--Remove Link to File<br>
</li>
<li><a href="utime.htm">utime()</a>--Set File Access and Modification Times<br>
</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 system:</p>
<pre>
#include &lt;sys/statvfs.h&gt;
#include &lt;stdio.h&gt;
main() {
struct statvfs info;
int fildes;
if (-1 == (fildes = open("/",O_RDONLY)))
perror("open() error");
else if (-1 == fstatvfs(fildes, &amp;info))
perror("fstatvfs() error");
else {
puts("fstatvfs() returned the following information");
puts("about the Root ('/') file system:");
printf(" f_bsize : %u\n", info.f_bsize);
printf(" f_blocks : %08X%08X\n",
*((int *)&amp;info.f_blocks[0]),
*((int *)&amp;info.f_blocks[4]));
printf(" f_bfree : %08X%08X\n",
*((int *)&amp;info.f_bfree[0]),
*((int *)&amp;info.f_bfree[4]));
printf(" f_files : %u\n", info.f_files);
printf(" f_ffree : %u\n", info.f_ffree);
printf(" f_fsid : %u\n", info.f_fsid);
printf(" f_flag : %X\n", info.f_flag);
printf(" f_namemax : %u\n", info.f_namemax);
printf(" f_pathmax : %u\n", info.f_pathmax);
printf(" f_basetype : %s\n", info.f_basetype);
}
}
</pre>
<p>Output: The following information will vary from file system to file
system.</p>
<pre>
statvfs() returned the following information
about the Root ('/') file system:
f_bsize : 4096
f_blocks : 00000000002BF800
f_bfree : 0000000000091703
f_files : 4294967295
f_ffree : 4294967295
f_fsid : 0
f_flag : 1A
f_namemax : 255
f_pathmax : 4294967295
f_basetype : "root" (/)
</pre>
<br>
<hr>
API introduced: V4R2
<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