S Parent topic: S

stat(), stat64()

Get information about a file or directory, given a path

Synopsis:

#include <sys/stat.h>

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

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

Arguments:

path
The path of the file or directory that you want information about.
buf
A pointer to a struct stat or struct stat64 buffer where the function can store the information.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The stat() and stat64() functions obtain information about the file or directory referenced in path. This information is placed in the structure located at the address indicated by buf. The stat64() function is a large-file support version of stat().

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see "Classification" in What's in a Function Description?

stat structure

Here's the stat structure that's defined in <sys/stat.h>: 

struct stat {
#if __OFF_BITS__ == 64
        ino_t                   st_ino;
        off_t                   st_size;
#elif __OFF_BITS__ == 32
# if defined(__LITTLEENDIAN__)
        ino_t                   st_ino;
        ino_t                   st_ino_hi;
        off_t                   st_size;
        off_t                   st_size_hi;
# elif defined(__BIGENDIAN__)
        ino_t                   st_ino_hi;
        ino_t                   st_ino;
        off_t                   st_size_hi;
        off_t                   st_size;
# else
#  error endian not configured for system
# endif
#else
# error __OFF_BITS__ value is unsupported
#endif
        _CSTD dev_t             st_dev;
        _CSTD dev_t             st_rdev;
        uid_t                   st_uid;
        gid_t                   st_gid;
        _CSTD time_t    st_mtime;
        _CSTD time_t    st_atime;
        _CSTD time_t    st_ctime;
        _CSTD mode_t    st_mode;
        nlink_t                 st_nlink;
        blksize_t               st_blocksize;
        int32_t                 st_nblocks;
        blksize_t               st_blksize;
#if __OFF_BITS__ == 64
        blkcnt_t                st_blocks;
#elif __OFF_BITS__ == 32
# if defined(__LITTLEENDIAN__)
        blkcnt_t                st_blocks;
        blkcnt_t                st_blocks_hi;
# elif defined(__BIGENDIAN__)
        blkcnt_t                st_blocks_hi;
        blkcnt_t                st_blocks;
# else
#  error endian not configured for system
# endif
#else
# error __OFF_BITS__ value is unsupported
#endif
};
#endif

#ifdef __EXT_LF64SRC
struct stat64 {
        ino64_t                 st_ino;
        off64_t                 st_size;
        _CSTD dev_t             st_dev;
        _CSTD dev_t             st_rdev;
        uid_t                   st_uid;
        gid_t                   st_gid;
        _CSTD time_t    st_mtime;
        _CSTD time_t    st_atime;
        _CSTD time_t    st_ctime;
        _CSTD mode_t    st_mode;
        nlink_t                 st_nlink;
        blksize_t               st_blocksize;
        int32_t                 st_nblocks;
        blksize_t               st_blksize;
        blkcnt64_t              st_blocks;
};
#endif

Access permissions

The access permissions for the file or directory are specified as a combination of bits in the st_mode field of a stat structure. These bits are defined in <sys/stat.h>, and are described below:

Owner Group Others Permission
S_IRUSR S_IRGRP S_IROTH Read
S_IRWXU S_IRWXG S_IRWXO Read, write, execute/search; a bitwise inclusive OR of the other three constants. (S_IRWXU is an OR of IRUSR, S_IWSUR and S_IXUSR.)
S_IWUSR S_IWGRP S_IWOTH Write
S_IXUSR S_IXGRP S_IXOTH Execute/search

The following bits define miscellaneous permissions used by other implementations:

Bit Equivalent
S_IEXEC S_IXUSR
S_IREAD S_IRUSR
S_IWRITE S_IWUSR

st_mode bits

The following bits are also encoded in the st_mode field:

S_ISUID
Set user ID on execution. The process's effective user ID is set to that of the owner of the file when the file is run as a program. On a regular file, this bit should be cleared on any write.
S_ISGID
Set group ID on execution. Set effective group ID on the process to the file's group when the file is run as a program. On a regular file, this bit should be cleared on any write.

File types

The following bits in st_mode identify the file type:

S_IFBLK
Block special.
S_IFCHR
Character special.
S_IFDIR
Directory.
S_IFIFO
FIFO special.
S_IFLNK
Symbolic link.
S_IFNAM
Special named file.
S_IFREG
Regular.
S_IFSOCK
Socket.

S_IFMT is a mask that isolates the above bits.

Macros

The following macros test whether a file is of a specified type. The value m supplied to the macros is the value of the st_mode field of a stat structure. The macros evaluate to a nonzero value if the test is true, and zero if the test is false.

S_ISBLK(m)
Test for block special file.
S_ISCHR(m)
Test for character special file.
S_ISDIR(m)
Test for directory file.
S_ISFIFO(m)
Test for FIFO.
S_ISLNK(m)
Test for symbolic link.
S_ISNAM(m)
Test for special named file.
S_ISREG(m)
Test for regular file.
S_ISSOCK(m)
Test for socket.

These macros test whether a file is of the specified type. The value of the buf argument supplied to the macros is a pointer to a stat structure. The macro evaluates to a nonzero value if the specified object is implemented as a distinct file type and the specified file type is contained in the stat structure referenced by the pointer buf. Otherwise, the macro evaluates to zero.

S_TYPEISMQ(buf)
Test for message queue.
S_TYPEISSEM(buf)
Test for semaphore.
S_TYPEISSHM(buf)
Test for shared memory object.

These macros manipulate device IDs:

major( device )
Extract the major number from a device ID.
minor( device )
Extract the minor number from a device ID.
makedev( node, major, minor)
Build a device ID from the given numbers. Currently, the node argument isn't used and must be zero.

The st_rdev member of the stat structure is a device ID that consists of:

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EACCES
Search permission is denied for a component of path.
EINTR
This function was interrupted by a signal.
EIO
A physical error occurred on the block device.
ELOOP
Too many levels of symbolic links or prefixes.
ENAMETOOLONG
The argument path exceeds PATH_MAX in length, or a pathname component is longer than NAME_MAX. These manifests are defined in the <limits.h> header file.
ENOENT
The named file doesn't exist, or path is an empty string.
ENOSYS
The stat() function isn't implemented for the filesystem specified in path.
ENOTDIR
A component of path isn't a directory.
EOVERFLOW
The file size in bytes or the number of blocks allocated to the file or the file serial number can't be represented correctly in the structure pointed to by buf.

Examples:

Determine the size of a file: 

#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>

int main( void )
  {
    struct stat buf;

    if( stat( "file", &buf ) != -1 ) {
      printf( "File size = %d\n", buf.st_size );
    }
    return EXIT_SUCCESS;
  }

Determine the amount of free memory: 

#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>

int main () {
   struct stat buf;
   
   if ( stat( "/proc", &buf ) == -1) {
      perror ("stat" );
      return EXIT_FAILURE;
   } else {
      printf ("Free memory: %d bytes\n", buf.st_size);
      return EXIT_SUCCESS;
   }
}

Classification:

stat() is POSIX 1003.1; stat64() is Large-file support

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes
Related reference
errno
fstat(), fstat64()
lstat(), lstat64()
struct stat
waitfor()
Parent topic: S