home *** CD-ROM | disk | FTP | other *** search
/ PC Extra Super CD 1998 January / PCPLUS131.iso / DJGPP / V2 / DJLSR201.ZIP / src / libc / posix / sys / stat / fstat.txh < prev    next >
Encoding:
Text File  |  1995-11-12  |  3.0 KB  |  77 lines
  1. @node fstat, stdio
  2. @subheading Syntax
  3.  
  4. @example
  5. #include <sys/stat.h>
  6.  
  7. int fstat(int file, struct stat *sbuf);
  8. @end example
  9.  
  10. @subheading Description
  11.  
  12. This function obtains the status of the open file @var{file} and stores
  13. it in @var{sbuf}.  @xref{stat} for the description of @code{struct stat}
  14. fields.
  15.  
  16. @subheading Return Value
  17.  
  18. Zero on success, nonzero on failure (and @var{errno} set). 
  19.  
  20. @subheading Example
  21.  
  22. @example
  23. struct stat s;
  24. fstat(fileno(stdin), &s);
  25. if (S_ISREG(s.st_mode))
  26.   puts("STDIN is a redirected disk file");
  27. else if (S_ISCHR(s.st_mode))
  28.   puts("STDIN is a character device");
  29. @end example
  30.  
  31. @subheading Bugs
  32.  
  33. If a file was open in write-only mode, its execute mode bits might be
  34. incorrectly reported as if the file were non-executable.  This is
  35. because some executables are only recognized by reading their first
  36. two bytes, which cannot be done for files open in write-only mode.
  37.  
  38. For @code{fstat()} to return valid info, you should make sure that all
  39. the data written to the file has been delivered to the operating system,
  40. e.g. by calling @code{fflush()}.  Otherwise, the buffering of the library
  41. I/O functions might cause stale info to be returned.
  42.  
  43. @subheading Implementation Notes
  44.  
  45. Supplying a 100% Unix-compatible @code{f?stat()} functions under DOS is an
  46. implementation nightmare.  The following notes describe some of the
  47. obscure points specific to their behavior in DJGPP.
  48.  
  49. 1. The @samp{drive} for character devices (like @code{con}, @code{/dev/nul}
  50. and others is returned as -1.  For drives networked by Novell Netware, it
  51. is returned as -2.
  52.  
  53. 2. The starting cluster number of a file serves as its inode number.  For
  54. files whose starting cluster number is inaccessible (empty files, files on
  55. networked drives, etc.) the @code{st_inode} field will be @cite{invented}
  56. in a way which guarantees that no two different files will get the same
  57. inode number (thus it is unique).  This invented inode will also be
  58. different from any real cluster number of any local file.  However, only
  59. for local, non-empty files/directories the inode is guaranteed to be
  60. consistent between @code{stat()} and @code{fstat()} function calls.
  61.  
  62. 3. The WRITE access mode bit is set only for the user (unless the file is
  63. read-only, hidden or system).  EXECUTE bit is set for directories,  files
  64. which can be executed from the DOS prompt (batch files, .com, .dll and .exe
  65. executables) or run by go32 extender.  For files which reside on networked
  66. drives under Novell Netware, this can sometimes fail, in which case only
  67. the read access bit is set.
  68.  
  69. 4. Size of directories is reported as the number of its files (sans `.' and
  70. `..' entries) multiplied by 32 bytes (the size of directory entry).
  71.  
  72. 5. Time stamp for root directories is taken from the volume label entry,
  73. if that's available; otherwise, it is reported as 1-Jan-1980.
  74.  
  75. 6. The variable @ref{_djstat_flags} controls what hard-to-get fields of
  76. @code{struct stat} are needed by the application.
  77.