home *** CD-ROM | disk | FTP | other *** search
/ PC Extra Super CD 1998 January / PCPLUS131.iso / DJGPP / V2 / DJLSR201.ZIP / src / libc / posix / sys / stat / stat.txh < prev    next >
Encoding:
Text File  |  1996-09-11  |  3.5 KB  |  89 lines
  1. @node stat, io
  2. @subheading Syntax
  3.  
  4. @example
  5. #include <sys/stat.h>
  6.  
  7. int stat(const char *file, struct stat *sbuf);
  8. @end example
  9.  
  10. @subheading Description
  11.  
  12. This function obtains the status of the file @var{file} and stores
  13. it in @var{sbuf}, which has this structure:
  14.  
  15. @example
  16. struct  stat @{
  17.         time_t   st_atime;     /* time of last modification */
  18.         time_t   st_ctime;     /*            ''             */
  19.         dev_t    st_dev;       /* The drive number (0 = a:) */
  20.         gid_t    st_gid;       /* getgid() */
  21.         ino_t    st_ino;       /* starting cluster or a unique identifier */
  22.         mode_t   st_mode;      /* file mode - S_IF* and S_IRUSR/S_IWUSR */
  23.         time_t   st_mtime;     /*            ''             */
  24.         nlink_t  st_nlink;     /* 2 + number of subdirs, or 1 for files */
  25.         off_t    st_size;      /* size of file in bytes */
  26.         off_t    st_blksize;   /* the size of transfer buffer */
  27.         uid_t    st_uid;       /* getuid() */
  28. @};
  29. @end example
  30.  
  31. @subheading Return Value
  32.  
  33. Zero on success, nonzero on failure (and @var{errno} set).
  34.  
  35. @subheading Example
  36.  
  37. @example
  38. struct stat s;
  39. stat("data.txt", &s);
  40. if (S_ISDIR(s.st_mode))
  41.   printf("is directory\n");
  42. @end example
  43.  
  44. @subheading Implementation Notes
  45.  
  46. Supplying a 100% Unix-compatible @code{f?stat()} functions under DOS is an
  47. implementation nightmare.  The following notes describe some of the
  48. obscure points specific to their behavior in DJGPP.
  49.  
  50. 1. The @samp{drive} for character devices (like @code{con}, @code{/dev/nul}
  51. and others is returned as -1.  For drives networked by Novell Netware, it
  52. is returned as -2.
  53.  
  54. 2. The starting cluster number of a file serves as its inode number.  For
  55. files whose starting cluster number is inaccessible (empty files, files on
  56. networked drives, etc.) the @code{st_inode} field will be @cite{invented}
  57. in a way which guarantees that no two different files will get the same
  58. inode number (thus it is unique).  This invented inode will also be
  59. different from any real cluster number of any local file.  However, only
  60. for local, non-empty files/directories the inode is guaranteed to be
  61. consistent between @code{stat()} and @code{fstat()} function calls.
  62.  
  63. 3. The WRITE access mode bit is set only for the user (unless the file is
  64. read-only, hidden or system).  EXECUTE bit is set for directories,  files
  65. which can be executed from the DOS prompt (batch files, .com, .dll and .exe
  66. executables) or run by go32 extender.
  67.  
  68. 4. Size of directories is reported as the number of its files (sans `.' and
  69. `..' entries) multiplied by 32 bytes (the size of directory entry).  On FAT
  70. filesystems that support the LFN API (such as Windows 9x), the reported
  71. size of the directory accounts for additional space used to store the long
  72. filenames.
  73.  
  74. 5. Time stamp for root directories is taken from the volume label entry,
  75. if that's available; otherwise, it is reported as 1-Jan-1980.
  76.  
  77. 6. The variable @ref{_djstat_flags} controls what hard-to-get fields of
  78. @code{struct stat} are needed by the application.
  79.  
  80. 7. @code{stat()} should not be used to get an up-to-date info about a file
  81. which is open and has been written to, because @code{stat()} will only
  82. return correct data after the file is closed.  Use @ref{fstat} while the
  83. file is open.
  84.  
  85. 8. The number of links @code{st_nlink} is always 1 for files other than
  86. directories.  For directories, it is the number of subdirectories plus
  87. 2.  This is so that programs written for Unix that depend on this to
  88. optimize recursive traversal of the directory tree, will still work.
  89.