From: Alejandro Colomar Date: Wed, 28 May 2025 18:44:28 +0000 (+0200) Subject: man/: Use '.member' notation for referring to struct/union members X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c99bfd43496f6ae3396fda67b5e0d8449cd04b06;p=thirdparty%2Fman-pages.git man/: Use '.member' notation for referring to struct/union members Signed-off-by: Alejandro Colomar --- diff --git a/man/man3/readdir.3 b/man/man3/readdir.3 index 83feef0fa..b9150160b 100644 --- a/man/man3/readdir.3 +++ b/man/man3/readdir.3 @@ -47,9 +47,9 @@ struct dirent { 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 @@ -57,29 +57,29 @@ The fields of the .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) @@ -91,7 +91,7 @@ since glibc 2.19, or .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 @@ -124,11 +124,11 @@ Currently, .\" 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 @@ -201,13 +201,13 @@ will require that 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, @@ -220,17 +220,17 @@ or .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[]", @@ -240,16 +240,16 @@ characters preceding the terminating null byte (\[aq]\[rs]0\[aq]). .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 @@ -263,10 +263,10 @@ fpathconf(fd, _PC_NAME_MAX) 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. diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type index 90a4623bd..ee801bcec 100644 --- a/man/man3type/stat.3type +++ b/man/man3type/stat.3type @@ -43,9 +43,9 @@ Feature Test Macro Requirements for glibc (see .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 @@ -57,7 +57,7 @@ Describes information about a file. .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) @@ -65,50 +65,50 @@ and .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 @@ -120,11 +120,12 @@ POSIX.1-2008. 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. @@ -134,7 +135,7 @@ Since Linux 2.5.48, the 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, @@ -151,7 +152,7 @@ or 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 .