The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> fstatvfs, statvfs - get file system information

#### SYNOPSIS

> ``#include <sys/statvfs.h>
> int fstatvfs(int` fildes`, struct statvfs *`buf`);
> int statvfs(const char *restrict` path`, struct statvfs *restrict` buf`);
> ``

#### DESCRIPTION

> The fstatvfs() function shall obtain information about the file system containing the file referenced by fildes.

> The statvfs() function shall obtain information about the file system containing the file named by path.

> For both functions, the buf argument is a pointer to a statvfs structure that shall be filled. Read, write, or execute permission of the named file is not required.

> The following flags can be returned in the f_flag member:

> ST_RDONLY
>   Read-only file system.
> ST_NOSUID
>   Setuid/setgid bits ignored by exec.

> It is unspecified whether all members of the statvfs structure have meaningful values on all file systems.

#### RETURN VALUE

> Upon successful completion, statvfs() shall return 0. Otherwise, it shall return -1 and set errno to indicate the error.

#### ERRORS

> The fstatvfs() and statvfs() functions shall fail if:

> [EIO]
>   An I/O error occurred while reading the file system.
> [EINTR]
>   A signal was caught during execution of the function.
> [EOVERFLOW]
>   One of the values to be returned cannot be represented correctly in the structure pointed to by buf.

> The fstatvfs() function shall fail if:

> [EBADF]
>   The fildes argument is not an open file descriptor.

> The statvfs() function shall fail if:

> [EACCES]
>   Search permission is denied on a component of the path prefix.
> [ELOOP]
>   A loop exists in symbolic links encountered during resolution of the path argument.
> [ENAMETOOLONG]
>   The length of a component of a pathname is longer than {NAME_MAX}.
> [ENOENT]
>   A component of path does not name an existing file or path is an empty string.
> [ENOTDIR]
>   A component of the path prefix names an existing file that is neither a directory nor a symbolic link to a directory, or the path argument contains at least one non- <slash> character and ends with one or more trailing <slash> characters and the last pathname component names an existing file that is neither a directory nor a symbolic link to a directory.

> The statvfs() function may fail if:

> [ELOOP]
>   More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.
> [ENAMETOOLONG]
>   The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.

The following sections are informative.

#### EXAMPLES

> ##### Obtaining File System Information Using fstatvfs()

> The following example shows how to obtain file system information for the file system upon which the file named /home/cnd/mod1 resides, using the fstatvfs() function. The /home/cnd/mod1 file is opened with read/write privileges and the open file descriptor is passed to the fstatvfs() function.

>     #include <sys/statvfs.h>
>     #include <fcntl.h>

>     struct statvfs buffer;
>     int            status;
>     ...
>     fildes = open("/home/cnd/mod1", O_RDWR);
>     status  = fstatvfs(fildes, &buffer);

> ##### Obtaining File System Information Using statvfs()

> The following example shows how to obtain file system information for the file system upon which the file named /home/cnd/mod1 resides, using the statvfs() function.

>     #include <sys/statvfs.h>

>     struct statvfs buffer;
>     int            status;
>     ...
>     status = statvfs("/home/cnd/mod1", &buffer);

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> chmod, chown, creat, dup, exec, fcntl, link, mknod, open, pipe, read, time, unlink, utime, write

> XBD <sys/statvfs.h>

#### CHANGE HISTORY

> First released in Issue 4, Version 2.

#### Issue 5

> Moved from X/OPEN UNIX extension to BASE.

> Large File Summit extensions are added.

#### Issue 6

> The normative text is updated to avoid use of the term "must" for application requirements.

> The restrict keyword is added to the statvfs() prototype for alignment with the ISO/IEC 9899:1999 standard.

> The wording of the mandatory [ELOOP] error condition is updated, and a second optional [ELOOP] error condition is added.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #143 is applied.

> SD5-XSH-ERN-68 is applied, correcting the EXAMPLES section.

> The fstatvfs() and statvfs() functions are moved from the XSI option to the Base.

> The [ENOTDIR] error condition is clarified to cover the condition where the last component of a pathname exists but is not a directory or a symbolic link to a directory.

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0203 [324] is applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]