statvfs()--Get File System Information

 #include <sys/statvfs.h>

 int statvfs(const char *path, struct statvfs *buf);  

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.

The f_flags field

The following symbols are defined in the <sys/statvfs.h> header file to refer to bits that may be returned in the f_flags 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.

Authorities

Note: Adopted authority is not used.

Authorization Required for statvfs()

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.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. 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
   
   
2. "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.

3. 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.)

4. 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

See Code disclaimer information for information pertaining to code examples.

The following example gets status information about a file system:

#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" (/)