* [PATCH 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7)
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
@ 2021-05-24 8:28 ` Alejandro Colomar
2021-05-24 8:53 ` Alejandro Colomar (man-pages)
2021-05-24 8:28 ` [PATCH 2/3] stat-struct.3: New link to system_data_types(7) Alejandro Colomar
` (5 subsequent siblings)
6 siblings, 1 reply; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 8:28 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
Move the definition of the struct present in stat(2), and put
there a reference to stat-struct(3) instead.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man2/stat.2 | 143 +--------------------------------------
man7/system_data_types.7 | 143 +++++++++++++++++++++++++++++++++++++++
2 files changed, 146 insertions(+), 140 deletions(-)
diff --git a/man2/stat.2 b/man2/stat.2
index d356ce15a..98424eb79 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -117,47 +117,8 @@ is specified by the file descriptor
.SS The stat structure
All of these system calls return a
.I stat
-structure, which contains the following fields:
-.PP
-.in +4n
-.EX
-struct stat {
- dev_t st_dev; /* ID of device containing file */
- ino_t st_ino; /* Inode number */
- mode_t st_mode; /* File type and mode */
- nlink_t st_nlink; /* Number of hard links */
- uid_t st_uid; /* User ID of owner */
- gid_t st_gid; /* Group ID of owner */
- dev_t st_rdev; /* Device ID (if special file) */
- off_t st_size; /* Total size, in bytes */
- blksize_t st_blksize; /* Block size for filesystem I/O */
- blkcnt_t st_blocks; /* Number of 512B blocks allocated */
-
- /* Since Linux 2.6, the kernel supports nanosecond
- precision for the following timestamp fields.
- For the details before Linux 2.6, see NOTES. */
-
- struct timespec st_atim; /* Time of last access */
- struct timespec st_mtim; /* Time of last modification */
- struct timespec st_ctim; /* Time of last status change */
-
-#define st_atime st_atim.tv_sec /* Backward compatibility */
-#define st_mtime st_mtim.tv_sec
-#define st_ctime st_ctim.tv_sec
-};
-.EE
-.in
-.PP
-.IR Note :
-the order of fields in the
-.I stat
-structure varies somewhat
-across architectures.
-In addition,
-the definition above does not show the padding bytes
-that may be present between some fields on various architectures.
-Consult the glibc and kernel source code
-if you need to know the details.
+structure (see
+.BR stat-struct (3)).
.PP
.\" Background: inode attributes are modified with i_mutex held, but
.\" read by stat() without taking the mutex.
@@ -183,69 +144,6 @@ or the old
.I st_uid
together with the new
.IR st_mode .
-.PP
-The fields in the
-.I stat
-structure are as follows:
-.TP
-.I st_dev
-This field describes the device on which this file resides.
-(The
-.BR major (3)
-and
-.BR minor (3)
-macros may be useful to decompose the device ID in this field.)
-.TP
-.I st_ino
-This field contains the file's inode number.
-.TP
-.I st_mode
-This field contains the file type and mode.
-See
-.BR inode (7)
-for further information.
-.TP
-.I st_nlink
-This field contains the number of hard links to the file.
-.TP
-.I st_uid
-This field contains the user ID of the owner of the file.
-.TP
-.I st_gid
-This field contains the ID of the group owner of the file.
-.TP
-.I st_rdev
-This field describes the device that this file (inode) represents.
-.TP
-.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
-This field gives the "preferred" block size for efficient filesystem I/O.
-.TP
-.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
-when the file has holes.)
-.TP
-.I st_atime
-This is the time of the last access of file data.
-.TP
-.I st_mtime
-This is the time of last modification of file data.
-.TP
-.I st_ctime
-This is the file's last status change timestamp
-(time of last change to the inode).
-.PP
-For further information on the above fields, see
-.BR inode (7).
-.\"
.SS fstatat()
The
.BR fstatat ()
@@ -491,42 +389,6 @@ fields may be less portable.
The interpretation differs between systems,
and possibly on a single system when NFS mounts are involved.)
.SH NOTES
-.SS Timestamp fields
-Older kernels and older standards did not support nanosecond timestamp
-fields.
-Instead, there were three timestamp
-.RI fields\(em st_atime ,
-.IR st_mtime ,
-and
-.IR st_ctime \(emtyped
-as
-.IR time_t
-that recorded timestamps with one-second precision.
-.PP
-Since kernel 2.5.48, the
-.I stat
-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 ,
-if suitable feature test macros are defined.
-Nanosecond timestamps were standardized in POSIX.1-2008,
-and, starting with version 2.12,
-glibc exposes the nanosecond component names if
-.BR _POSIX_C_SOURCE
-is defined with the value 200809L or greater, or
-.BR _XOPEN_SOURCE
-is defined with the value 700 or greater.
-Up to and including glibc 2.19,
-the definitions of the nanoseconds components are also defined if
-.B _BSD_SOURCE
-or
-.B _SVID_SOURCE
-is defined.
-If none of the aforementioned macros are defined,
-then the nanosecond values are exposed with names of the form
-.IR st_atimensec .
-.\"
.SS C library/kernel differences
Over time, increases in the size of the
.I stat
@@ -707,6 +569,7 @@ main(int argc, char *argv[])
.BR readlink (2),
.BR statx (2),
.BR utime (2),
+.BR stat-struct (3),
.BR capabilities (7),
.BR inode (7),
.BR symlink (7)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 6f6f8a095..64e25fa56 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1433,6 +1433,149 @@ and
.I size_t
types in this page.
.RE
+.\"------------------------------------- stat -------------------------/
+.TP
+.I stat
+.RS
+.IR Include :
+.IR <sys/stat.h> .
+Alternatively,
+.IR <ftw.h> .
+.PP
+.EX
+struct stat {
+ dev_t st_dev; /* ID of device containing file */
+ ino_t st_ino; /* Inode number */
+ mode_t st_mode: /* File type and mode */
+ nlink_t st_nlink; /* Number of hard links */
+ uid_t st_uid; /* User ID of owner */
+ gid_t st_gid; /* Group ID of owner */
+ dev_t st_rdev; /* Device ID (if special file) */
+ off_t st_size; /* Total size, in bytes */
+ blksize_t st_blksize; /* Block size for filesystem I/O */
+ blkcnt_t st_blocks; /* Number of 512 B blocks allocated */
+
+ /* Since POSIX.1-2008, this structure supports nanosecond
+ precision for the following timestamp fields.
+ For the details before POSIX.1-2008, see Notes. */
+
+ struct timespec st_atim; /* Time of last access */
+ struct timespec st_mtim; /* Time of last modification */
+ struct timespec st_ctim; /* Time of last status change */
+
+#define st_atime st_atim.tv_sec /* Backward compatibility */
+#define st_mtine st_mtim.tv_sec
+#define st_ctime st_ctim.tv_sec
+};
+.EE
+.PP
+Describes information about a file.
+.PP
+The fields are as follows:
+.TP
+.I st_dev
+This field describes the device on which this file resides.
+(The
+.BR major (3)
+and
+.BR minor (3)
+macros may be useful to decompose the device ID in this field.)
+.TP
+.I st_ino
+This field contains the file's inode number.
+.TP
+.I st_mode
+This field contains the file type and mode.
+See
+.BR inode (7)
+for further information.
+.TP
+.I st_nlink
+This field contains the number of hard links to the file.
+.TP
+.I st_uid
+This field contains the user ID of the owner of the file.
+.TP
+.I st_gid
+This field contains the ID of the group owner of the file.
+.TP
+.I st_rdev
+This field describes the device that this file (inode) represents.
+.TP
+.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
+This field gives the "preferred" block size for efficient filesystem I/O.
+.TP
+.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
+when the file has holes.)
+.TP
+.I st_atime
+This is the time of the last access of file data.
+.TP
+.I st_mtime
+This is the time of last modification of file data.
+.TP
+.I st_ctime
+This is the file's last status change timestamp
+(time of last change to the inode).
+.PP
+For further information on the above fields, see
+.BR inode (7).
+.\"
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later (see Notes).
+.PP
+.IR Notes :
+Old kernels and old standards did not support nanosecond timestamp fields.
+Instead, there were three timestamp
+.RI fields\(em st_atime ,
+.IR st_mtime ,
+and
+.IR st_ctime \(emtyped
+as
+.IR time_t
+that recorded timestamps with one-second precision.
+.PP
+Since Linux 2.5.48, the
+.I stat
+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 ,
+if suitable test macros are defined.
+Nanosecond timestamps were standardized in POSIX.1-2008,
+and, starting with version 2.12,
+glibc exposes the nanosecond component names if
+.BR _POSIX_C_SOURCE
+is defined with the value 200809L or greater, or
+.BR _XOPEN_SOURCE
+is defined with the value 700 or greater.
+Up to and including glibc 2.19,
+the definitions of the nanoseconds components are also defined if
+.B _BSD_SOURCE
+or
+.B _SVID_SOURCE
+is defined.
+If none of the aforementioned macros are defined,
+then the nanosecond values are exposed with names of the form
+.IR st_atimensec .
+.PP
+.IR "See also" :
+.BR accept (2),
+.BR getpeername (2),
+.BR getsockname (2),
+.BR socket (2)
+.RE
.\"------------------------------------- suseconds_t ------------------/
.TP
.I suseconds_t
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 2/3] stat-struct.3: New link to system_data_types(7)
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
2021-05-24 8:28 ` [PATCH 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7) Alejandro Colomar
@ 2021-05-24 8:28 ` Alejandro Colomar
2021-05-24 8:48 ` [PATCH 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix Alejandro Colomar
` (4 subsequent siblings)
6 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 8:28 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man3/stat-struct.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/stat-struct.3
diff --git a/man3/stat-struct.3 b/man3/stat-struct.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/stat-struct.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
2021-05-24 8:28 ` [PATCH 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7) Alejandro Colomar
2021-05-24 8:28 ` [PATCH 2/3] stat-struct.3: New link to system_data_types(7) Alejandro Colomar
@ 2021-05-24 8:48 ` Alejandro Colomar
2021-05-24 8:56 ` Alejandro Colomar (man-pages)
2021-05-24 9:13 ` [PATCH v2 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7) Alejandro Colomar
` (3 subsequent siblings)
6 siblings, 1 reply; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 8:48 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
This avoids shadowing other pages, and clearly differentiates
function pages from type pages (both are in man3).
Do this for struct/union types, and not for typedefs. This makes
sense because typedefs in C are in the same namespace as function
identifiers, but struct and union (and enum) tags are in a
different one, and can have the same name as a function.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man3/{aiocb.3 => aiocb-struct.3} | 0
man3/{lconv.3 => lconv-struct.3} | 0
man3/{sigval.3 => sigval-struct.3} | 0
man3/{sockaddr.3 => sockaddr-union.3} | 0
man3/{timespec.3 => timespec-struct.3} | 0
man3/{timeval.3 => timeval-struct.3} | 0
man3/sigevent-struct.3 | 1 +
7 files changed, 1 insertion(+)
rename man3/{aiocb.3 => aiocb-struct.3} (100%)
rename man3/{lconv.3 => lconv-struct.3} (100%)
rename man3/{sigval.3 => sigval-struct.3} (100%)
rename man3/{sockaddr.3 => sockaddr-union.3} (100%)
rename man3/{timespec.3 => timespec-struct.3} (100%)
rename man3/{timeval.3 => timeval-struct.3} (100%)
create mode 100644 man3/sigevent-struct.3
diff --git a/man3/aiocb.3 b/man3/aiocb-struct.3
similarity index 100%
rename from man3/aiocb.3
rename to man3/aiocb-struct.3
diff --git a/man3/lconv.3 b/man3/lconv-struct.3
similarity index 100%
rename from man3/lconv.3
rename to man3/lconv-struct.3
diff --git a/man3/sigval.3 b/man3/sigval-struct.3
similarity index 100%
rename from man3/sigval.3
rename to man3/sigval-struct.3
diff --git a/man3/sockaddr.3 b/man3/sockaddr-union.3
similarity index 100%
rename from man3/sockaddr.3
rename to man3/sockaddr-union.3
diff --git a/man3/timespec.3 b/man3/timespec-struct.3
similarity index 100%
rename from man3/timespec.3
rename to man3/timespec-struct.3
diff --git a/man3/timeval.3 b/man3/timeval-struct.3
similarity index 100%
rename from man3/timeval.3
rename to man3/timeval-struct.3
diff --git a/man3/sigevent-struct.3 b/man3/sigevent-struct.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigevent-struct.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PATCH 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix
2021-05-24 8:48 ` [PATCH 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix Alejandro Colomar
@ 2021-05-24 8:56 ` Alejandro Colomar (man-pages)
0 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-05-24 8:56 UTC (permalink / raw)
To: mtk.manpages; +Cc: G . Branden Robinson, linux-man
On 5/24/21 10:48 AM, Alejandro Colomar wrote:
> This avoids shadowing other pages, and clearly differentiates
> function pages from type pages (both are in man3).
>
> Do this for struct/union types, and not for typedefs. This makes
> sense because typedefs in C are in the same namespace as function
> identifiers, but struct and union (and enum) tags are in a
> different one, and can have the same name as a function.
>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
> ---
> man3/{aiocb.3 => aiocb-struct.3} | 0
> man3/{lconv.3 => lconv-struct.3} | 0
> man3/{sigval.3 => sigval-struct.3} | 0
> man3/{sockaddr.3 => sockaddr-union.3} | 0
> man3/{timespec.3 => timespec-struct.3} | 0
> man3/{timeval.3 => timeval-struct.3} | 0
> man3/sigevent-struct.3 | 1 +
> 7 files changed, 1 insertion(+)
> rename man3/{aiocb.3 => aiocb-struct.3} (100%)
> rename man3/{lconv.3 => lconv-struct.3} (100%)
> rename man3/{sigval.3 => sigval-struct.3} (100%)
> rename man3/{sockaddr.3 => sockaddr-union.3} (100%)
> rename man3/{timespec.3 => timespec-struct.3} (100%)
> rename man3/{timeval.3 => timeval-struct.3} (100%)
> create mode 100644 man3/sigevent-struct.3
There are some struct/union tags wrong. I'll fix it.
>
> diff --git a/man3/aiocb.3 b/man3/aiocb-struct.3
> similarity index 100%
> rename from man3/aiocb.3
> rename to man3/aiocb-struct.3
> diff --git a/man3/lconv.3 b/man3/lconv-struct.3
> similarity index 100%
> rename from man3/lconv.3
> rename to man3/lconv-struct.3
> diff --git a/man3/sigval.3 b/man3/sigval-struct.3
> similarity index 100%
> rename from man3/sigval.3
> rename to man3/sigval-struct.3
> diff --git a/man3/sockaddr.3 b/man3/sockaddr-union.3
> similarity index 100%
> rename from man3/sockaddr.3
> rename to man3/sockaddr-union.3
> diff --git a/man3/timespec.3 b/man3/timespec-struct.3
> similarity index 100%
> rename from man3/timespec.3
> rename to man3/timespec-struct.3
> diff --git a/man3/timeval.3 b/man3/timeval-struct.3
> similarity index 100%
> rename from man3/timeval.3
> rename to man3/timeval-struct.3
> diff --git a/man3/sigevent-struct.3 b/man3/sigevent-struct.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigevent-struct.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH v2 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7)
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
` (2 preceding siblings ...)
2021-05-24 8:48 ` [PATCH 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix Alejandro Colomar
@ 2021-05-24 9:13 ` Alejandro Colomar
2021-05-24 9:13 ` [PATCH v2 2/3] stat-struct.3: New link to system_data_types(7) Alejandro Colomar
` (2 subsequent siblings)
6 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 9:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
Move the definition of the struct present in stat(2), and put
there a reference to stat-struct(3) instead.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man2/stat.2 | 143 +--------------------------------------
man7/system_data_types.7 | 141 +++++++++++++++++++++++++++++++++++++++
2 files changed, 144 insertions(+), 140 deletions(-)
diff --git a/man2/stat.2 b/man2/stat.2
index d356ce15a..98424eb79 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -117,47 +117,8 @@ is specified by the file descriptor
.SS The stat structure
All of these system calls return a
.I stat
-structure, which contains the following fields:
-.PP
-.in +4n
-.EX
-struct stat {
- dev_t st_dev; /* ID of device containing file */
- ino_t st_ino; /* Inode number */
- mode_t st_mode; /* File type and mode */
- nlink_t st_nlink; /* Number of hard links */
- uid_t st_uid; /* User ID of owner */
- gid_t st_gid; /* Group ID of owner */
- dev_t st_rdev; /* Device ID (if special file) */
- off_t st_size; /* Total size, in bytes */
- blksize_t st_blksize; /* Block size for filesystem I/O */
- blkcnt_t st_blocks; /* Number of 512B blocks allocated */
-
- /* Since Linux 2.6, the kernel supports nanosecond
- precision for the following timestamp fields.
- For the details before Linux 2.6, see NOTES. */
-
- struct timespec st_atim; /* Time of last access */
- struct timespec st_mtim; /* Time of last modification */
- struct timespec st_ctim; /* Time of last status change */
-
-#define st_atime st_atim.tv_sec /* Backward compatibility */
-#define st_mtime st_mtim.tv_sec
-#define st_ctime st_ctim.tv_sec
-};
-.EE
-.in
-.PP
-.IR Note :
-the order of fields in the
-.I stat
-structure varies somewhat
-across architectures.
-In addition,
-the definition above does not show the padding bytes
-that may be present between some fields on various architectures.
-Consult the glibc and kernel source code
-if you need to know the details.
+structure (see
+.BR stat-struct (3)).
.PP
.\" Background: inode attributes are modified with i_mutex held, but
.\" read by stat() without taking the mutex.
@@ -183,69 +144,6 @@ or the old
.I st_uid
together with the new
.IR st_mode .
-.PP
-The fields in the
-.I stat
-structure are as follows:
-.TP
-.I st_dev
-This field describes the device on which this file resides.
-(The
-.BR major (3)
-and
-.BR minor (3)
-macros may be useful to decompose the device ID in this field.)
-.TP
-.I st_ino
-This field contains the file's inode number.
-.TP
-.I st_mode
-This field contains the file type and mode.
-See
-.BR inode (7)
-for further information.
-.TP
-.I st_nlink
-This field contains the number of hard links to the file.
-.TP
-.I st_uid
-This field contains the user ID of the owner of the file.
-.TP
-.I st_gid
-This field contains the ID of the group owner of the file.
-.TP
-.I st_rdev
-This field describes the device that this file (inode) represents.
-.TP
-.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
-This field gives the "preferred" block size for efficient filesystem I/O.
-.TP
-.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
-when the file has holes.)
-.TP
-.I st_atime
-This is the time of the last access of file data.
-.TP
-.I st_mtime
-This is the time of last modification of file data.
-.TP
-.I st_ctime
-This is the file's last status change timestamp
-(time of last change to the inode).
-.PP
-For further information on the above fields, see
-.BR inode (7).
-.\"
.SS fstatat()
The
.BR fstatat ()
@@ -491,42 +389,6 @@ fields may be less portable.
The interpretation differs between systems,
and possibly on a single system when NFS mounts are involved.)
.SH NOTES
-.SS Timestamp fields
-Older kernels and older standards did not support nanosecond timestamp
-fields.
-Instead, there were three timestamp
-.RI fields\(em st_atime ,
-.IR st_mtime ,
-and
-.IR st_ctime \(emtyped
-as
-.IR time_t
-that recorded timestamps with one-second precision.
-.PP
-Since kernel 2.5.48, the
-.I stat
-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 ,
-if suitable feature test macros are defined.
-Nanosecond timestamps were standardized in POSIX.1-2008,
-and, starting with version 2.12,
-glibc exposes the nanosecond component names if
-.BR _POSIX_C_SOURCE
-is defined with the value 200809L or greater, or
-.BR _XOPEN_SOURCE
-is defined with the value 700 or greater.
-Up to and including glibc 2.19,
-the definitions of the nanoseconds components are also defined if
-.B _BSD_SOURCE
-or
-.B _SVID_SOURCE
-is defined.
-If none of the aforementioned macros are defined,
-then the nanosecond values are exposed with names of the form
-.IR st_atimensec .
-.\"
.SS C library/kernel differences
Over time, increases in the size of the
.I stat
@@ -707,6 +569,7 @@ main(int argc, char *argv[])
.BR readlink (2),
.BR statx (2),
.BR utime (2),
+.BR stat-struct (3),
.BR capabilities (7),
.BR inode (7),
.BR symlink (7)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 6f6f8a095..64e25fa56 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -1433,6 +1433,147 @@ and
.I size_t
types in this page.
.RE
+.\"------------------------------------- stat -------------------------/
+.TP
+.I stat
+.RS
+.IR Include :
+.IR <sys/stat.h> .
+Alternatively,
+.IR <ftw.h> .
+.PP
+.EX
+struct stat {
+ dev_t st_dev; /* ID of device containing file */
+ ino_t st_ino; /* Inode number */
+ mode_t st_mode: /* File type and mode */
+ nlink_t st_nlink; /* Number of hard links */
+ uid_t st_uid; /* User ID of owner */
+ gid_t st_gid; /* Group ID of owner */
+ dev_t st_rdev; /* Device ID (if special file) */
+ off_t st_size; /* Total size, in bytes */
+ blksize_t st_blksize; /* Block size for filesystem I/O */
+ blkcnt_t st_blocks; /* Number of 512 B blocks allocated */
+
+ /* Since POSIX.1-2008, this structure supports nanosecond
+ precision for the following timestamp fields.
+ For the details before POSIX.1-2008, see Notes. */
+
+ struct timespec st_atim; /* Time of last access */
+ struct timespec st_mtim; /* Time of last modification */
+ struct timespec st_ctim; /* Time of last status change */
+
+#define st_atime st_atim.tv_sec /* Backward compatibility */
+#define st_mtine st_mtim.tv_sec
+#define st_ctime st_ctim.tv_sec
+};
+.EE
+.PP
+Describes information about a file.
+.PP
+The fields are as follows:
+.TP
+.I st_dev
+This field describes the device on which this file resides.
+(The
+.BR major (3)
+and
+.BR minor (3)
+macros may be useful to decompose the device ID in this field.)
+.TP
+.I st_ino
+This field contains the file's inode number.
+.TP
+.I st_mode
+This field contains the file type and mode.
+See
+.BR inode (7)
+for further information.
+.TP
+.I st_nlink
+This field contains the number of hard links to the file.
+.TP
+.I st_uid
+This field contains the user ID of the owner of the file.
+.TP
+.I st_gid
+This field contains the ID of the group owner of the file.
+.TP
+.I st_rdev
+This field describes the device that this file (inode) represents.
+.TP
+.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
+This field gives the "preferred" block size for efficient filesystem I/O.
+.TP
+.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
+when the file has holes.)
+.TP
+.I st_atime
+This is the time of the last access of file data.
+.TP
+.I st_mtime
+This is the time of last modification of file data.
+.TP
+.I st_ctime
+This is the file's last status change timestamp
+(time of last change to the inode).
+.PP
+For further information on the above fields, see
+.BR inode (7).
+.\"
+.PP
+.IR "Conforming to" :
+POSIX.1-2001 and later (see Notes).
+.PP
+.IR Notes :
+Old kernels and old standards did not support nanosecond timestamp fields.
+Instead, there were three timestamp
+.RI fields\(em st_atime ,
+.IR st_mtime ,
+and
+.IR st_ctime \(emtyped
+as
+.IR time_t
+that recorded timestamps with one-second precision.
+.PP
+Since Linux 2.5.48, the
+.I stat
+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 ,
+if suitable test macros are defined.
+Nanosecond timestamps were standardized in POSIX.1-2008,
+and, starting with version 2.12,
+glibc exposes the nanosecond component names if
+.BR _POSIX_C_SOURCE
+is defined with the value 200809L or greater, or
+.BR _XOPEN_SOURCE
+is defined with the value 700 or greater.
+Up to and including glibc 2.19,
+the definitions of the nanoseconds components are also defined if
+.B _BSD_SOURCE
+or
+.B _SVID_SOURCE
+is defined.
+If none of the aforementioned macros are defined,
+then the nanosecond values are exposed with names of the form
+.IR st_atimensec .
+.PP
+.IR "See also" :
+.BR stat (2),
+.BR inode (7)
+.RE
.\"------------------------------------- suseconds_t ------------------/
.TP
.I suseconds_t
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 2/3] stat-struct.3: New link to system_data_types(7)
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
` (3 preceding siblings ...)
2021-05-24 9:13 ` [PATCH v2 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7) Alejandro Colomar
@ 2021-05-24 9:13 ` Alejandro Colomar
2021-05-24 9:13 ` [PATCH v2 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix Alejandro Colomar
2021-07-03 18:10 ` Adding struct-xxx link pages for structures Alejandro Colomar (man-pages)
6 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 9:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man3/stat-struct.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/stat-struct.3
diff --git a/man3/stat-struct.3 b/man3/stat-struct.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/stat-struct.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH v2 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
` (4 preceding siblings ...)
2021-05-24 9:13 ` [PATCH v2 2/3] stat-struct.3: New link to system_data_types(7) Alejandro Colomar
@ 2021-05-24 9:13 ` Alejandro Colomar
2021-07-03 18:10 ` Adding struct-xxx link pages for structures Alejandro Colomar (man-pages)
6 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar @ 2021-05-24 9:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: Alejandro Colomar, G . Branden Robinson, linux-man
This avoids shadowing other pages, and clearly differentiates
function pages from type pages (both are in man3).
Do this for struct/union types, and not for typedefs. This makes
sense because typedefs in C are in the same namespace as function
identifiers, but struct and union (and enum) tags are in a
different one, and can have the same name as a function.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man3/{aiocb.3 => aiocb-struct.3} | 0
man3/{lconv.3 => lconv-struct.3} | 0
man3/{sigval.3 => sigval-union.3} | 0
man3/{sockaddr.3 => sockaddr-struct.3} | 0
man3/{timespec.3 => timespec-struct.3} | 0
man3/{timeval.3 => timeval-struct.3} | 0
man3/sigevent-struct.3 | 1 +
7 files changed, 1 insertion(+)
rename man3/{aiocb.3 => aiocb-struct.3} (100%)
rename man3/{lconv.3 => lconv-struct.3} (100%)
rename man3/{sigval.3 => sigval-union.3} (100%)
rename man3/{sockaddr.3 => sockaddr-struct.3} (100%)
rename man3/{timespec.3 => timespec-struct.3} (100%)
rename man3/{timeval.3 => timeval-struct.3} (100%)
create mode 100644 man3/sigevent-struct.3
diff --git a/man3/aiocb.3 b/man3/aiocb-struct.3
similarity index 100%
rename from man3/aiocb.3
rename to man3/aiocb-struct.3
diff --git a/man3/lconv.3 b/man3/lconv-struct.3
similarity index 100%
rename from man3/lconv.3
rename to man3/lconv-struct.3
diff --git a/man3/sigval.3 b/man3/sigval-union.3
similarity index 100%
rename from man3/sigval.3
rename to man3/sigval-union.3
diff --git a/man3/sockaddr.3 b/man3/sockaddr-struct.3
similarity index 100%
rename from man3/sockaddr.3
rename to man3/sockaddr-struct.3
diff --git a/man3/timespec.3 b/man3/timespec-struct.3
similarity index 100%
rename from man3/timespec.3
rename to man3/timespec-struct.3
diff --git a/man3/timeval.3 b/man3/timeval-struct.3
similarity index 100%
rename from man3/timeval.3
rename to man3/timeval-struct.3
diff --git a/man3/sigevent-struct.3 b/man3/sigevent-struct.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigevent-struct.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.31.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: Adding struct-xxx link pages for structures
2021-05-23 21:04 ` Alejandro Colomar (man-pages)
` (5 preceding siblings ...)
2021-05-24 9:13 ` [PATCH v2 3/3] aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix Alejandro Colomar
@ 2021-07-03 18:10 ` Alejandro Colomar (man-pages)
6 siblings, 0 replies; 13+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-07-03 18:10 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: Michael Kerrisk (man-pages), linux-man
Hi Branden,
On 5/23/21 11:04 PM, Alejandro Colomar (man-pages) wrote:
> On 5/23/21 10:53 PM, Alejandro Colomar (man-pages) wrote:
>>> The use of a dash/minus as a separator "feels" unorthodox to me, but
>>> perhaps that is just the pull of blind tradition. I think it's actually
>>> a better choice than an underscore because of course "-" is not valid in
>>> a C identifier, and "_" is, so ambiguity is avoided.
>>
>> I used struct-foo because man has the ability to allow either
>> 'man struct-foo' or 'man struct foo', and the latter looks very
>> intuitive from a C-syntax perspective (I learnt this from the git manual
>> pages, where you can do 'man git log' or 'man git-log'). 'man man'
>> doesn't specify this behavior, so I'll read the source code and try to
>> confirm how it works.
>
> I would need some time to understand the code, but perhaps it's around
> lines 1303 or 1396
>
> .../man-db$ grep -rn "'-'" src/man.c;
> 1013: if (dbfilters && (dbfilters[0] != '-') && !preprocessors) {
> 1303: case '-':
> 1396: if (*pp_string == ' ' || *pp_string == '-')
> 2921: if (*source->pointer != '-')
> 3222: if (*in->pointer != '-')
> .../man-db$ grep -rn "' '" src/man.c;
> 797: case ' ':
> 810: if (*(manopt + 1) == ' ')
> 1302: case ' ':
> 1396: if (*pp_string == ' ' || *pp_string == '-')
> 2415: putchar (' ');
> 4051: } else if (cmd[i] == '\t' || cmd[i] == ' ' || cmd[i] ==
> '\n' ||
> $
A few weeks ago I found out that '_' can also be replaced by a space in
man. i.e., `man foo_struct` and `man foo struct` would be equivalent.
However, as you pointed out, I think it's better to use '_' to avoid
using valid C identifiers.
Kind regards,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 13+ messages in thread