unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



stat(2)								      stat(2)



NAME

  stat,	fstat, lstat - Provides	information about a file

SYNOPSIS

  #include <&lt;sys/types.h>&gt;
  #include <&lt;sys/stat.h>&gt;

  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():  POSIX.1, XSH5.0

  lstat():  POSIX.1, XSH5.0

  stat():  POSIX.1, XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try 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 <&lt;sys/stat.h>&gt;	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
  <&lt;sys/mode.h>&gt;.

  The fstat() function is like the stat() function except that the informa-
  tion 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 for st_blocks is the	number of blocks in the	original file at the
  time the clone fileset was created.

NOTES

  Two structure	members	in <&lt;stat.h>&gt; uniquely identify a	file in	a file sys-
  tem:	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 <&lt;stat.h>&gt;, the file generation number, is needed to uniquely	iden-
  tify 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 parame-
	    ter.

  [EFAULT]  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 filename 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]  The	buffer parameter points	to a location outside of the allo-
	    cated address space	of the process.

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

RELATED	INFORMATION

  Functions: chmod(2), chown(2), link(2), mknod(2), open(2), pipe(2), sym-
  link(2), utime(2)

  Standards: standards(5)