statvfs()--Get File System Information
Syntax
#include <sys/statvfs.h> int statvfs(const char *path, struct statvfs *buf);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The statvfs() function gets status information about the file system that contains the file named by the path argument. The information will be placed in the area of memory pointed to by the buf argument.
If the named file is a symbolic link, statvfs() resolves the symbolic link.
Parameters
- path
- (Input) A pointer to the null-terminated path name of the file from which
file system information is required.
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.
See QlgStatvfs()--Get File System Information (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.
- buf
- (Output) A pointer to the area to which the information should be written.
The information is returned in the following statvfs structure, as defined in the <sys/statvfs.h> header file. Signed fields of the statvfs structure that are not supported by the mounted file system will be set to -1.
unsigned long | f_bsize | 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 f_blocks, f_bfree, and
f_bavail fields are undefined. |
unsigned long | f_frsize | 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 f_blocks, f_bfree, and
f_bavail fields are undefined. |
_Bin8 | f_blocks | The total number of blocks in the file system in
terms of f_frsize. |
_Bin8 | f_bfree | The total number of free blocks in the file
system. |
_Bin8 | f_bavail | The total number of free blocks available to a
non-privileged process. |
unsigned long | f_files | The total number of file serial numbers. |
unsigned long | f_ffree | The total number of free file serial numbers. |
unsigned long | f_favail | The number of free file serial numbers available
to a non-privileged process. |
unsigned long | f_fsid | The file system ID. This field will be
4,294,967,295 if the value could not fit in the specified unsigned long
field. |
unsigned long | f_flag | File system flags. Symbols are defined in the
<sys/statvfs.h> header file to refer to bits in this
field (see The f_flag field). |
unsigned long | f_namemax | The maximum file name length in the file system.
Some file systems may return the maximum value that can be stored in an
unsigned long to indicate the file system has no maximum file name
length. The maximum value that can be stored in an unsigned long
is defined in <limits.h> as ULONG_MAX.
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. |
unsigned long | f_pathmax | The maximum path length in the file system. Some
file systems may return the maximum value that can be stored in an
unsigned long to indicate the file system has no maximum path length.
The maximum value that can be stored in an unsigned long is
defined in <limits.h> as ULONG_MAX.
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. |
long | f_objlinkmax | The maximum number of hard links for objects
other than directories. |
long | f_dirlinkmax | The maximum number of hard links for a
directory. |
char | f_reserved1[4] | Reserved. |
unsigned long long | f_fsid64 | The file system ID in 64 bit format. |
char | f_basetype[80] | 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. |
The f_flag field
The following symbols are defined in the <sys/statvfs.h> header file to refer to bits that may be returned in the f_flag field:
- ST_RDONLY
- The file system is mounted for read-only access.
- ST_NOSUID
- The file system does not support setuid/setgid semantics.
- ST_CASE_SENSITIVE
- The file system is case sensitive.
- ST_CHOWN_RESTRICTED
- The file system restricts the changing of the owner or primary group to a process that has the appropriate privileges.
- ST_THREAD_SAFE
- The file system is thread-safe. Thread-safe APIs may operate on objects in this file system in a thread-safe manner.
- ST_DYNAMIC_MOUNT
- The file system allows itself to be dynamically mounted and unmounted.
- ST_NO_MOUNT_OVER
- The file system does not allow any part of it to be mounted over.
- ST_NO_EXPORTS
- The file system does not allow any of its objects to be exported to the Network File System (NFS) Server.
- ST_SYNCHRONOUS
- The file system supports the "synchronous write" semantic of NFS Version 2.
- ST_TEMPORARY
- The file system contains only temporary objects.
- ST_SSD_PREFERRED
- The file system's preferred storage media is solid state drive storage. Storage for the objects contained in the file system should be allocated from solid state drive storage media, if available.
Authorities
Note: Adopted authority is not used.
Authorization Required for statvfs()
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name that precedes the object | *X | EACCES |
Object | None | None |
Return Value
- 0
- statvfs() was successful. The information is returned in buf.
- -1
- statvfs() was not successful. The errno global variable is set to indicate the error.
Error Conditions
If statvfs() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
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. |
[EAGAIN] | |
[EBADFID] | |
[EBADNAME] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EFAULT] | |
[EFILECVT] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[ELOOP] | |
[ENAMETOOLONG] | |
[ENOENT] | |
[ENOMEM] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTDIR] | |
[ENOTSAFE] | |
[EPERM] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist in the job.
- 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:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- "Root" (/) and QOpenSys File System Differences
These file systems return the f_flag field with the ST_NOSUID flag bit turned off. However, support for the setuid/setgid semantics is limited to the ability to store and retrieve the S_ISUID and S_ISGID flags when these file systems are accessed from the Network File System server.
- Network File System Differences
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.)
- When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, it will be mapped to statvfs64(). Additionally, the struct statvfs data type will be mapped to a struct statvfs64.
Related Information
- The <sys/statvfs.h> file (see
Header Files for UNIX®-Type Functions)
- The <sys/types.h> file (see
Header Files for UNIX-Type Functions)
- chmod()--Change File Authorizations
- chown()--Change Owner and Group of File
- creat()--Create or Rewrite File
- dup()--Duplicate Open File Descriptor
- fclear()--Write (Binary Zeros) to Descriptor
- fclear64()--Write (Binary Zeros) to Descriptor
- fcntl()--Perform File Control Command
- fstatvfs()--Get File System Information by
Descriptor
- link()--Create Link to File
- open()--Open File
- QlgStatvfs()--Get File System Information (using
NLS-enabled path name)
- read()--Read from Descriptor
- statvfs64()--Get File System Information (64-Bit
Enabled)
- unlink()--Remove Link to File
- utime()--Set File Access and Modification Times
- write()--Write to Descriptor
Example
The following example gets status information about a file system.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#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); } }
Output: The following information will vary from file system to file system.
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" (/)
API introduced: V4R2
Top | UNIX-Type APIs | APIs by category |