The only fields in the
.I dirent
structure that are mandated by POSIX.1 are
-.I d_name
+.I .d_name
and
-.IR d_ino .
+.IR .d_ino .
The other fields are unstandardized, and not present on all systems;
see VERSIONS.
.P
.I dirent
structure are as follows:
.TP
-.I d_ino
+.I .d_ino
This is the inode number of the file.
.TP
-.I d_off
+.I .d_off
The value returned in
-.I d_off
+.I .d_off
is the same as would be returned by calling
.BR telldir (3)
at the current position in the directory stream.
Be aware that despite its type and name, the
-.I d_off
+.I .d_off
field is seldom any kind of directory offset on modern filesystems.
.\" https://lwn.net/Articles/544298/
Applications should treat this field as an opaque value,
making no assumptions about its contents; see also
.BR telldir (3).
.TP
-.I d_reclen
+.I .d_reclen
This is the size (in bytes) of the returned record.
This may not match the size of the structure definition shown above;
see VERSIONS.
.TP
-.I d_type
+.I .d_type
This field contains a value indicating the file type,
making it possible to avoid the expense of calling
.BR lstat (2)
.B _BSD_SOURCE
on glibc 2.19 and earlier),
glibc defines the following macro constants for the value returned in
-.IR d_type :
+.IR .d_type :
.RS
.TP 12
.B DT_BLK
.\" The same sentence is in getdents.2
only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
have full support for returning the file type in
-.IR d_type .
+.IR .d_type .
All applications must properly handle a return of
.BR DT_UNKNOWN .
.TP
-.I d_name
+.I .d_name
This field contains the null terminated filename;
see VERSIONS.
.P
be thread-safe when concurrently employed on different directory streams.
.SH VERSIONS
Only the fields
-.I d_name
+.I .d_name
and (as an XSI extension)
-.I d_ino
+.I .d_ino
are specified in POSIX.1.
.\" POSIX.1-2001, POSIX.1-2008
Other than Linux, the
-.I d_type
+.I .d_type
field is available mainly only on BSD systems.
The remaining fields are available on many, but not all systems.
Under glibc,
.B _DIRENT_HAVE_D_TYPE
are defined.
.\"
-.SS The d_name field
+.SS The \f[I].d_name\f[] field
The
.I dirent
structure definition shown above is taken from the glibc headers,
and shows the
-.I d_name
+.I .d_name
field with a fixed size.
.P
.IR Warning :
applications should avoid any dependence on the size of the
-.I d_name
+.I .d_name
field.
POSIX defines it as
.IR "char\ d_name[]",
.P
POSIX.1 explicitly notes that this field should not be used as an lvalue.
The standard also notes that the use of
-.I sizeof(d_name)
+.I sizeof(.d_name)
is incorrect; use
-.I strlen(d_name)
+.I strlen(.d_name)
instead.
(On some systems, this field is defined as
.IR char\~d_name[1] !)
By implication, the use
.I sizeof(struct dirent)
to capture the size of the record including the size of
-.I d_name
+.I .d_name
is also incorrect.
.P
Note that while the call
returns the value 255 for most filesystems,
on some filesystems (e.g., CIFS, Windows SMB servers),
the null-terminated filename that is (correctly) returned in
-.I d_name
+.I .d_name
can actually exceed this size.
In such cases, the
-.I d_reclen
+.I .d_reclen
field will contain a value that exceeds the size of the glibc
.I dirent
structure shown above.
.BR feature_test_macros (7)):
.RE
.P
-.IR st_atim ,
-.IR st_mtim ,
-.IR st_ctim :
+.IR .st_atim ,
+.IR .st_mtim ,
+.IR .st_ctim :
.nf
Since glibc 2.12:
_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700
.P
The fields are as follows:
.TP
-.I st_dev
+.I .st_dev
This field describes the device on which this file resides.
(The
.BR major (3)
.BR minor (3)
macros may be useful to decompose the device ID in this field.)
.TP
-.I st_ino
+.I .st_ino
This field contains the file's inode number.
.TP
-.I st_mode
+.I .st_mode
This field contains the file type and mode.
See
.BR inode (7)
for further information.
.TP
-.I st_nlink
+.I .st_nlink
This field contains the number of hard links to the file.
.TP
-.I st_uid
+.I .st_uid
This field contains the user ID of the owner of the file.
.TP
-.I st_gid
+.I .st_gid
This field contains the ID of the group owner of the file.
.TP
-.I st_rdev
+.I .st_rdev
This field describes the device that this file (inode) represents.
.TP
-.I st_size
+.I .st_size
This field gives the size of the file (if it is a regular
file or a symbolic link) in bytes.
The size of a symbolic link is the length of the pathname
it contains, without a terminating null byte.
.TP
-.I st_blksize
+.I .st_blksize
This field gives the "preferred" block size for efficient filesystem I/O.
.TP
-.I st_blocks
+.I .st_blocks
This field indicates the number of blocks allocated to the file,
in 512-byte units.
(This may be smaller than
-.IR st_size /512
+.IR .st_size /512
when the file has holes.)
.TP
-.I st_atime
+.I .st_atime
This is the time of the last access of file data.
.TP
-.I st_mtime
+.I .st_mtime
This is the time of last modification of file data.
.TP
-.I st_ctime
+.I .st_ctime
This is the file's last status change timestamp
(time of last change to the inode).
.P
POSIX.1-2001.
.P
Old kernels and old standards did not support nanosecond timestamp fields.
-Instead, there were three timestamp
-.RI fields\[em] st_atime ,
-.IR st_mtime ,
+Instead, there were three timestamp fields
+.RI \[em] .st_atime ,
+.IR .st_mtime ,
and
-.IR st_ctime \[em]typed
+.IR .st_ctime \[em]
+typed
as
.I time_t
that recorded timestamps with one-second precision.
structure supports nanosecond resolution for the three file timestamp fields.
The nanosecond components of each timestamp are available
via names of the form
-.IR st_atim.tv_nsec ,
+.IR .st_atim.tv_nsec ,
if suitable test macros are defined.
Nanosecond timestamps were standardized in POSIX.1-2008,
and, starting with glibc 2.12,
is defined.
If none of the aforementioned macros are defined,
then the nanosecond values are exposed with names of the form
-.IR st_atimensec .
+.IR .st_atimensec .
.SH NOTES
The following header also provides this type:
.IR <ftw.h> .
projects / thirdparty / man-pages.git / commitdiff
