Adding struct-xxx link pages for structures

Adding struct-xxx link pages for structures

[Alejandro Colomar (man-pages)]

Hi Michael,

We have some structures defined in system_data_types(7) for which we 
don't have a link page, because it would have shadowed other more 
important pages.

I've been documenting 'struct stat', and it happens the same: I'd shadow 
stat(2) with stat(3).

But I need to refer to stat(3) (or whatever link page we decide to have) 
from stat(2).  So I need one (referring to system_data_types(7) isn't 
very informative).

How about adding struct-stat(2)?

However, that means that we should also add struct-xxx(3) / union-xxx(3) 
for all of the structs/unions we have documented there (one might 
reasonably expect to be able to find struct-aiocb(3) or union-sigval(3) 
if there's a struct-stat(3)).

What do you think about it?

Thanks,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Adding struct-xxx link pages for structures

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2385 bytes --]

Hi Alex,

At 2021-05-23T16:03:30+0200, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> We have some structures defined in system_data_types(7) for which we
> don't have a link page, because it would have shadowed other more
> important pages.
> 
> I've been documenting 'struct stat', and it happens the same: I'd
> shadow stat(2) with stat(3).
> 
> But I need to refer to stat(3) (or whatever link page we decide to
> have) from stat(2).  So I need one (referring to system_data_types(7)
> isn't very informative).
> 
> How about adding struct-stat(2)?
> 
> However, that means that we should also add struct-xxx(3) /
> union-xxx(3) for all of the structs/unions we have documented there
> (one might reasonably expect to be able to find struct-aiocb(3) or
> union-sigval(3) if there's a struct-stat(3)).
> 
> What do you think about it?

You didn't ask me, but I'd recommend reversing the order, to put the
most important information first, and that's the structure (or union)
tag, not the "struct" or "union" keyword tag itself.

I think the common use case is someone who has the tag in mind (or needs
to know it exists) and is looking for it.  It is less common that
someone is going to want to browse every such page.  We don't want to
discourage such curiosity, but I think such people can be accommodated
easily, say in the libc(7) man page.  (In fact, I think that page could
be made even more useful by giving a synoptical view of the C Standard
Library, but that's a digression and, like a good intro(1), no small
task.)

Putting the tag first will also help in the tab completion case, because
the tag name will be less ambiguous than "struct".  We can easily
imagine someone typing "man struct<TAB>" and getting blitzed with a
menu of dozens of items.

If I do that for "stat" on my system, I get this:

$ man stat
stat      stat64    states    statfs    statfs64  statvfs   statx

Seeing "stat-struct" in that list would leave me with little doubt as to
what the page will cover, even with the manual section missing.

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.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Adding struct-xxx link pages for structures

[Alejandro Colomar (man-pages)]

Hi Branden,

On 5/23/21 4:26 PM, G. Branden Robinson wrote:
 > You didn't ask me,

Your feedback is, as always has been, very valuable and appreciated :-)

If I sometimes don't answer to some of your mails, it's because I don't
have enough background to understand it, and prefer to wait for an
answer of Michael ;)

 > but I'd recommend reversing the order, to put the
 > most important information first, and that's the structure (or union)
 > tag, not the "struct" or "union" keyword tag itself.

Hmm, interesting.

 >
 > I think the common use case is someone who has the tag in mind (or needs
 > to know it exists) and is looking for it.

Agree.

 > It is less common that
 > someone is going to want to browse every such page.  We don't want to
 > discourage such curiosity, but I think such people can be accommodated
 > easily, say in the libc(7) man page.  (In fact, I think that page could
 > be made even more useful by giving a synoptical view of the C Standard
 > Library, but that's a digression and, like a good intro(1), no small
 > task.)

Interesting idea too.

Ideally, for functions, that would be as easy as listing all of the
pages in man3  (right now that would be mixing functions and types; for
something more precise, see my function man_lsfunc() in
<scripts/bash_aliases>).

I think it's very unlucky that historically there hasn't been a section
for the types, so that we could do the same with the types, and now
we're (ab)using section 3 (BTW, do you have any opinion on this?  I'm
not sure how we should proceed with that in the long term).
Specifically, I think that we're breaking the ability of listing all of
the pages to know which functions there are.  I thought of adding a new
subsection (maybe 3t) for types.

And there's also another thing:  there's no way of listing constants
(you either read the standards documents (or the manual pages) entirely
(and you will miss implementation-specific details), or read the source
code (and become crazy in the process)).

 >
 > Putting the tag first will also help in the tab completion case, because
 > the tag name will be less ambiguous than "struct".  We can easily
 > imagine someone typing "man struct<TAB>" and getting blitzed with a
 > menu of dozens of items.
 >
 > If I do that for "stat" on my system, I get this:
 >
 > $ man stat
 > stat      stat64    states    statfs    statfs64  statvfs   statx
 >
 > Seeing "stat-struct" in that list would leave me with little doubt as to
 > what the page will cover, even with the manual section missing.

Yes.  Maybe a simpler option to having an entirely new subsection would
be to always have a suffix -struct (or _struct) (or [-_]union) for types
(others (typedefs) already have _t).

 >
 > 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.

Regards,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Adding struct-xxx link pages for structures

[Alejandro Colomar (man-pages)]

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' ||
$

 >
 > Regards,
 >
 > Alex
 >

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7)

[Alejandro Colomar]

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

[PATCH 2/3] stat-struct.3: New link to system_data_types(7)

[Alejandro Colomar]

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

[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]

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

Re: [PATCH 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7)

[Alejandro Colomar (man-pages)]

On 5/24/21 10:28 AM, Alejandro Colomar wrote:
...
> +.IR "See also" :
> +.BR accept (2),
> +.BR getpeername (2),
> +.BR getsockname (2),
> +.BR socket (2)

Oops, let me fix this in a moment.

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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

[Alejandro Colomar (man-pages)]

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/

[PATCH v2 1/3] stat.2, system_data_types.7: Document 'struct stat' in system_data_types(7)

[Alejandro Colomar]

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

[PATCH v2 2/3] stat-struct.3: New link to system_data_types(7)

[Alejandro Colomar]

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

[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]

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

Re: Adding struct-xxx link pages for structures

[Alejandro Colomar (man-pages)]

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/