man0p/dirent.h.0p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "<dirent.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" <dirent.h>
   4 .SH NAME
   5 dirent.h \- format of directory entries
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <dirent.h>\fP
   9 .SH DESCRIPTION
  10 .LP
  11 The internal format of directories is unspecified.
  12 .LP
  13 The \fI<dirent.h>\fP header shall define the following type:
  14 .TP 7
  15 \fBDIR\fP
  16 A type representing a directory stream.
  17 .sp
  18 .LP
  19 It shall also define the structure \fBdirent\fP which shall include
  20 the following members:
  21 .sp
  22 .RS
  23 .nf
  24
  25 \fB
  26 ino_t  d_ino      \fP File serial number. \fB
  27
  28 char   d_name[]   \fP Name of entry. \fB
  29 \fP
  30 .fi
  31 .RE
  32 .LP
  33 The type \fBino_t\fP shall be defined as described in \fI<sys/types.h>\fP
  34 \&.
  35 .LP
  36 The character array \fId_name\fP is of unspecified size, but the number
  37 of bytes preceding the terminating null byte shall not
  38 exceed {NAME_MAX}.
  39 .LP
  40 The following shall be declared as functions and may also be defined
  41 as macros. Function prototypes shall be provided.
  42 .sp
  43 .RS
  44 .nf
  45
  46 \fBint            closedir(DIR *);
  47 DIR           *opendir(const char *);
  48 struct dirent *readdir(DIR *);
  49
  50 int            readdir_r(DIR *restrict, struct dirent *restrict,
  51                    struct dirent **restrict);
  52
  53 void           rewinddir(DIR *);
  54
  55 void           seekdir(DIR *, long);
  56 long           telldir(DIR *);
  57
  58 \fP
  59 .fi
  60 .RE
  61 .LP
  62 \fIThe following sections are informative.\fP
  63 .SH APPLICATION USAGE
  64 .LP
  65 None.
  66 .SH RATIONALE
  67 .LP
  68 Information similar to that in the \fI<dirent.h>\fP header is contained
  69 in a file \fI<sys/dir.h>\fP in 4.2 BSD and
  70 4.3 BSD. The equivalent in these implementations of \fBstruct dirent\fP
  71 from this volume of IEEE\ Std\ 1003.1-2001 is
  72 \fBstruct direct\fP. The filename was changed because the name \fI<sys/dir.h>\fP
  73 was also used in earlier implementations
  74 to refer to definitions related to the older access method; this produced
  75 name conflicts. The name of the structure was changed
  76 because this volume of IEEE\ Std\ 1003.1-2001 does not completely
  77 define what is in the structure, so it could be different
  78 on some implementations from \fBstruct direct\fP.
  79 .LP
  80 The name of an array of \fBchar\fP of an unspecified size should not
  81 be used as an lvalue. Use of:
  82 .sp
  83 .RS
  84 .nf
  85
  86 \fBsizeof(d_name)
  87 \fP
  88 .fi
  89 .RE
  90 .LP
  91 is incorrect; use:
  92 .sp
  93 .RS
  94 .nf
  95
  96 \fBstrlen(d_name)
  97 \fP
  98 .fi
  99 .RE
 100 .LP
 101 instead.
 102 .LP
 103 The array of \fBchar\fP \fId_name\fP is not a fixed size. Implementations
 104 may need to declare \fBstruct dirent\fP with an
 105 array size for \fId_name\fP of 1, but the actual number of characters
 106 provided matches (or only slightly exceeds) the length of
 107 the filename.
 108 .SH FUTURE DIRECTIONS
 109 .LP
 110 None.
 111 .SH SEE ALSO
 112 .LP
 113 \fI<sys/types.h>\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
 114 \fIclosedir\fP(), \fIopendir\fP(), \fIreaddir\fP(), \fIreaddir_r\fP(),
 115 \fIrewinddir\fP(), \fIseekdir\fP(), \fItelldir\fP()
 116 .SH COPYRIGHT
 117 Portions of this text are reprinted and reproduced in electronic form
 118 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 119 -- Portable Operating System Interface (POSIX), The Open Group Base
 120 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 121 Electrical and Electronics Engineers, Inc and The Open Group. In the
 122 event of any discrepancy between this version and the original IEEE and
 123 The Open Group Standard, the original IEEE and The Open Group Standard
 124 is the referee document. The original Standard can be obtained online at
 125 http://www.opengroup.org/unix/online.html .