<!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>statvfs()--Get File System Information</title> <!-- 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. --> <!-- Begin Header Records ========================================== --> <!-- 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: --> <!-- 010405 JTROUS Add new field descriptions, V5R2, 98391 --> <!-- 011022 JTROUS Changes from API Review 1, V5R2 --> <!-- 020618 EMIG: updated for NFS threadsafety, V5R3 --> <!-- 020624 RTHEIS: Add fclear() and fclear64(), V5R3 --> <!-- 0206?? JET This file has undergone html cleanup June 2002 by JET--> <!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 --> <!-- 021107 JTROUS Add desc to blksize,allocsize, V5R3 --> <!-- 050407 JTROUS: fix enums, no change flag, V5R4 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <h2>statvfs()--Get File System Information</h2> <div class="box" style="width: 60%;"> <br> Syntax<br> <pre> #include <sys/statvfs.h> int statvfs(const char <em>*path</em>, struct statvfs <em>*buf</em>); </pre> Service Program Name: QP0LLIB1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Conditional; see <a href="#HDRSTVFUSG">Usage Notes</a>.<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>statvfs()</strong> function gets status information about the file system that contains the file named by the <em>path</em> argument. The information will be placed in the area of memory pointed to by the <em>buf</em> argument.</p> <p>If the named file is a symbolic link, <strong>statvfs()</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 from which file system 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="statvfsu.htm">QlgStatvfs()--Get File System 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>statvfs</samp> structure, as defined in the <<strong>sys/statvfs.h</strong>> header file. Signed fields of the <samp>statvfs</samp> structure that are not supported by the mounted file system will be set to -1.</p> <table border> <!-- cols="15 15 70" --> <tr> <td align="left" valign="top" width="15%">unsigned long</td> <td align="left" valign="top" width="15%">f_bsize</td> <td align="left" valign="top" width="70%">The file system block size in bytes. This number is the number of bytes in a block of disk unit storage. Some file systems may return zero in this field. If this field is zero, then the contents of the <samp>f_blocks</samp>, <samp>f_bfree</samp>, and <samp> f_bavail</samp> fields are undefined.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_frsize</td> <td align="left" valign="top">The fundamental file system block size in bytes. Some file systems may return zero in this field. If this field is zero, then the contents of the <samp>f_blocks</samp>, <samp>f_bfree</samp>, and <samp> f_bavail</samp> fields are undefined.<br> <br> </td> </tr> <tr> <td align="left" valign="top">_Bin8</td> <td align="left" valign="top">f_blocks</td> <td align="left" valign="top">The total number of blocks in the file system in terms of <samp>f_frsize</samp>.<br> <br> </td> </tr> <tr> <td align="left" valign="top">_Bin8</td> <td align="left" valign="top">f_bfree</td> <td align="left" valign="top">The total number of free blocks in the file system.<br> <br> </td> </tr> <tr> <td align="left" valign="top">_Bin8</td> <td align="left" valign="top">f_bavail</td> <td align="left" valign="top">The total number of free blocks available to a non-privileged process.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_files</td> <td align="left" valign="top">The total number of file serial numbers.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_ffree</td> <td align="left" valign="top">The total number of free file serial numbers.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_favail</td> <td align="left" valign="top">The number of free file serial numbers available to a non-privileged process.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_fsid</td> <td align="left" valign="top">The file system ID. This field will be 4,294,967,295 if the value could not fit in the specified unsigned long field.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_flag</td> <td align="left" valign="top">File system flags. Symbols are defined in the <<strong>sys/statvfs.h</strong>> header file to refer to bits in this field (see <a href="#HDRFFLAGS">The f_flags field</a>).<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_namemax</td> <td align="left" valign="top">The maximum file name length in the file system. Some file systems may return the maximum value that can be stored in an <samp> unsigned long</samp> to indicate the file system has no maximum file name length. The maximum value that can be stored in an <samp>unsigned long</samp> is defined in <<strong>limits.h</strong>> as ULONG_MAX. <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.<br> <br> </p> </td> </tr> <tr> <td align="left" valign="top">unsigned long</td> <td align="left" valign="top">f_pathmax</td> <td align="left" valign="top">The maximum path length in the file system. Some file systems may return the maximum value that can be stored in an <samp> unsigned long</samp> to indicate the file system has no maximum path length. The maximum value that can be stored in an <samp>unsigned long</samp> is defined in <<strong>limits.h</strong>> as ULONG_MAX. <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.<br> <br> </p> </td> </tr> <tr> <td align="left" valign="top">long</td> <td align="left" valign="top">f_objlinkmax</td> <td align="left" valign="top">The maximum number of hard links for objects other than directories.<br> <br> </td> </tr> <tr> <td align="left" valign="top">long</td> <td align="left" valign="top">f_dirlinkmax</td> <td align="left" valign="top">The maximum number of hard links for a directory.<br> <br> </td> </tr> <tr> <td align="left" valign="top">char</td> <td align="left" valign="top">f_reserved1[4]</td> <td align="left" valign="top">Reserved.<br> <br> </td> </tr> <tr> <td align="left" valign="top">unsigned long long</td> <td align="left" valign="top">f_fsid64</td> <td align="left" valign="top">The file system ID in 64 bit format.<br> <br> </td> </tr> <tr> <td align="left" valign="top">char</td> <td align="left" valign="top">f_basetype[80]</td> <td align="left" valign="top">The NULL-terminated file system type name. The text in this field will be returned in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this is assumed to be represented in the default CCSID of the job.</td> </tr> </table> <br> <h5><a name="HDRFFLAGS">The f_flags field</a></h5> <p>The following symbols are defined in the <<strong>sys/statvfs.h</strong>> header file to refer to bits that may be returned in the <samp>f_flags</samp> field:</p> <dl compact> <dt><em>ST_RDONLY</em></dt> <dd>The file system is mounted for read-only access.</dd> <dt><em>ST_NOSUID</em></dt> <dd>The file system does not support setuid/setgid semantics.</dd> <dt><em>ST_CASE_SENSITIVE</em></dt> <dd>The file system is case sensitive.</dd> <dt><em>ST_CHOWN_RESTRICTED</em></dt> <dd>The file system restricts the changing of the owner or primary group to a process that has the appropriate privileges.</dd> <dt><em>ST_THREAD_SAFE</em></dt> <dd>The file system is thread-safe. Thread-safe APIs may operate on objects in this file system in a thread-safe manner.</dd> <dt><em>ST_DYNAMIC_MOUNT</em></dt> <dd>The file system allows itself to be dynamically mounted and unmounted.</dd> <dt><em>ST_NO_MOUNT_OVER</em></dt> <dd>The file system does not allow any part of it to be mounted over.</dd> <dt><em>ST_NO_EXPORTS</em></dt> <dd>The file system does not allow any of its objects to be exported to the Network File System (NFS) Server.</dd> <dt><em>ST_SYNCHRONOUS</em></dt> <dd>The file system supports the "synchronous write" semantic of NFS Version 2.</dd> </dl> <br> <h3><a name="HDRSTVFAUT">Authorities</a></h3> <p><strong>Note:</strong> Adopted authority is not used.</p> <p><strong><a name="TBLBSTATFS">Authorization Required for statvfs()</a></strong></p> <table border> <!-- cols="60 20 20" --> <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" width="90%">Each directory in the path name that precedes the object</td> <td align="left" valign="top" width="5%">*X</td> <td align="left" valign="top" width="5%">EACCES</td> </tr> <tr> <td align="left" valign="top" width="90%">Object</td> <td align="left" valign="top" width="5%">None</td> <td align="left" valign="top" width="5%">None</td> </tr> </table> <br> <br> <h3>Return Value</h3> <dl compact> <dt><em>0</em></dt> <dd><strong>statvfs()</strong> was successful. The information is returned in <em>buf</em>.</dd> <dt><em>-1</em></dt> <dd><strong>statvfs()</strong> was not successful. The <em>errno</em> global variable is set to indicate the error.</dd> </dl> <br> <h3><a name="HDRSTVFERR">Error Conditions</a></h3> <p>If <strong>statvfs()</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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONVERT">ECONVERT</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EFILECVT">EFILECVT</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EIO">EIO</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EPERM">EPERM</a>]</em></td> <td align="left" valign="top"> </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"> </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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td> <td align="left" valign="top"> </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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td> <td align="left" valign="top"> </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 &1.</td> </tr> <tr> <td valign="top">CPF3CF2 E</td> <td valign="top">Error(s) occurred during running of &1 API.</td> </tr> <tr> <td valign="top">CPF9872 E</td> <td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> </table> <br> <br> <h3><a name="HDRSTVFUSG">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> </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. 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>When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, it will be mapped to <strong>statvfs64()</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 <<strong>sys/statvfs.h</strong>> file (see <a href="unix13.htm"> Header Files for UNIX-Type Functions</a>)<br> </li> <li>The <<strong>sys/types.h</strong>> 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</li> <li><a href="fclear64.htm">fclear64()</a>--Write (Binary Zeros) to Descriptor</li> <li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br> </li> <li><a href="fstatvfs.htm">fstatvfs()</a>--Get File System Information by Descriptor<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="statvfsu.htm">QlgStatvfs()</a>--Get File System Information (using NLS-enabled path name)<br> </li> <li><a href="read.htm">read()</a>--Read from Descriptor<br> </li> <li><a href="statvf64.htm">statvfs64()</a>--Get File System Information (64-Bit Enabled)<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 <sys/statvfs.h> #include <stdio.h> main() { struct statvfs info; if (-1 == statvfs("/", &info)) perror("statvfs() error"); else { puts("statvfs() 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 *)&info.f_blocks[0]), *((int *)&info.f_blocks[4])); printf(" f_bfree : %08X%08X\n", *((int *)&info.f_bfree[0]), *((int *)&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>