Index for Section 2

Alphabetical listing for S

Bottom of page

stat(2)
NAME
  stat, fstat, lstat - Provide information about a file

SYNOPSIS
  #include <sys/types.h>
  #include <sys/stat.h>

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

  int lstat(
	  const char *path,
	  struct stat *buffer );

  int fstat(
	  int filedes,
	  struct stat *buffer );

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  fstat(), stat(): POSIX.1, XSH4.0, XSH4.2, XSH5.0

  lstat(): POSIX.1, XSH4.2, XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  path
      Specifies the pathname identifying the file.

  filedes
      Specifies the file descriptor identifying the open file.

  buffer
      Points to the stat structure in which information is returned. The stat
      structure is described in the <sys/stat.h> header file.

DESCRIPTION
  The stat() function obtains information about the file named by the path
  parameter. Read, write, or execute permission for the named file is not
  required, but all directories listed in the pathname leading to the file
  must be searchable. The file information is written to the area specified
  by the buffer parameter, which is a pointer to a stat structure, defined in
  <sys/stat.h>.

  The values of the stat structure's member, mode_t, are defined in
  <sys/mode.h>.

  The fstat() function is like the stat() function except that the
  information obtained is about an open file referenced by the filedes
  parameter.

  The lstat() function is like the stat() function except in the case where
  the named file is a symbolic link. In this case, the lstat() function
  returns information about the link, while the stat() and fstat() functions
  return information about the file the link references. In the case of a
  symbolic link, the stat() functions set the st_size field of the stat
  structure to the length of the symbolic link, and sets the st_mode field to
  indicate the file type.

  The stat(), lstat(), and fstat() functions update any time-related fields
  associated with the file before writing into the stat structure.

  [Tru64 UNIX]	When run on a file in an AdvFS clone fileset, the value
  returned in the st_blocks field is the number of blocks in the original
  file at the time the clone fileset was created.

NOTES
  Two structure members in <sys/stat.h> uniquely identify a file in a file
  system: st_ino, the file serial number, and st_dev, the device id for the
  directory that contains the file.

  [Tru64 UNIX]	However, in the rare case when a user application has been
  deleting open files, and a file serial number is reused, a third structure
  member in <sys/stat.h>, the file generation number, is needed to uniquely
  identify a file. This member, st_gen, is used in addition to st_ino and
  st_dev.

RETURN VALUES
  Upon successful completion, a value of 0 (zero) is returned. Otherwise, a
  value of -1 is returned and errno is set to indicate the error.

ERRORS
  If the stat() or lstat() function fails, errno may be set to one of the
  following values:

  [EACCES]
      Search permission is denied for a component of the path parameter.

  [EFAULT]
      [Tru64 UNIX]  Either the buffer parameter or the path parameter points
      to a location outside of the allocated address space of the process.

  [EIO]
      An I/O error occurred while reading from the file system.

  [ELOOP]
      Too many links were encountered in translating path.

  [ENAMETOOLONG]
      The length of the path parameter exceeds PATH_MAX or a pathname
      component is longer than NAME_MAX.

  [ENOENT]
      The file named by the path parameter does not exist or is an empty
      string.

  [ENOTDIR]
      A component of the path parameter is not a directory.

  [Tru64 UNIX]	For NFS file access, if the stat() or lstat() function fails,
  errno may also be set to one of the following values:

  [EINVAL]
      The file position pointer associated with the filedes parameter was
      negative.

  [EISDIR]
      Indicates either that the request was for a write access to a file but
      the specified file name was actually a directory, or that the function
      was trying to rename a directory as a file.

  [ENFILE]
      Indicates either that the system file table is full, or that there are
      too many files currently open in the system.

  [ESTALE]
      Indicates a stale NFS file handle. An opened file was deleted by the
      server or another client; a client cannot open a file because the
      server has unmounted or unexported the remote directory; or the
      directory that contains an opened file was either unmounted or
      unexported by the server.

  If the fstat() function fails, errno may be set to one of the following
  values:

  [EBADF]
      The filedes parameter is not a valid file descriptor.

  [EFAULT]
      [Tru64 UNIX]  The buffer parameter points to a location outside of the
      allocated address space of the process.

  [EIO]
      An I/O error occurred while reading from the file system.

SEE ALSO
  Functions: chmod(2), chown(2), link(2), mknod(2), open(2), pipe(2),
  symlink(2), utime(2)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for S

Top of page