[src/trunk]: src/share/man/man4 unix(4): Fix/add markup

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b116c6b04242
branches:  trunk
changeset: 372543:b116c6b04242
user:      uwe <uwe%NetBSD.org@localhost>
date:      Tue Dec 06 15:06:40 2022 +0000

description:
unix(4): Fix/add markup

Untabify examples, .Bd -literal -offset indent doesn't seem to mesh
with tabs nicely in the PostScript output.  The indent is probably not
a multiple a of literal tab width.  This causes a small vertical
misalignment for tab-indented lines, but what's worse - it can cause
an extra tab in some cases (and did here for the unpcbid definition).

diffstat:

 share/man/man4/unix.4 |  81 +++++++++++++++++++++++++++++---------------------
 1 files changed, 47 insertions(+), 34 deletions(-)

diffs (176 lines):

diff -r 8e369a7c9324 -r b116c6b04242 share/man/man4/unix.4
--- a/share/man/man4/unix.4     Tue Dec 06 01:14:36 2022 +0000
+++ b/share/man/man4/unix.4     Tue Dec 06 15:06:40 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: unix.4,v 1.29 2022/08/28 10:48:16 hgutch Exp $
+.\"    $NetBSD: unix.4,v 1.30 2022/12/06 15:06:40 uwe Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -64,9 +64,9 @@
 defines this address:
 .Bd -literal -offset indent
 struct sockaddr_un {
-       u_char  sun_len;
-       u_char  sun_family;
-       char    sun_path[104];
+        u_char  sun_len;
+        u_char  sun_family;
+        char    sun_path[104];
 };
 .Ed
 .Pp
@@ -92,7 +92,7 @@
 defined in
 .In sys/un.h .
 The
-.Ar sun_path
+.Fa sun_path
 field must be terminated by a NUL character to be used with
 .Fn SUN_LEN ,
 but the terminating NUL is
@@ -101,7 +101,7 @@
 The
 .Nx
 kernel ignores any user-set value in the
-.Va sun_len
+.Fa sun_len
 member of the structure.
 .Pp
 The
@@ -137,9 +137,9 @@
 sockets also support the communication of
 .Ux
 file descriptors through the use of the
-.Ar msg_control
+.Fa msg_control
 field in the
-.Ar msg
+.Fa msg
 argument to
 .Xr sendmsg 2
 and
@@ -147,7 +147,7 @@
 .Pp
 Any valid descriptor may be sent in a message.
 The file descriptor(s) to be passed are described using a
-.Ar struct cmsghdr
+.Vt struct cmsghdr
 that is defined in the include file
 .In sys/socket.h .
 The type of the message is
@@ -172,7 +172,9 @@
 purposely not received, are automatically closed by the system
 when the destination socket is closed.
 .Pp
-A UNIX-domain socket supports several
+A
+.Ux Ns -domain
+socket supports several
 .Dv SOL_LOCAL
 level options for use with
 .Xr setsockopt 2
@@ -191,20 +193,28 @@
 receive the credentials of the process as a
 .Xr recvmsg 2
 control message.
-The msg_control field in the msghdr structure points
-to a buffer that contains a cmsghdr structure followed by a variable
-length sockcred structure, defined in
+The
+.Fa msg_control
+field in the
+.Vt msghdr
+structure points
+to a buffer that contains a
+.Vt cmsghdr
+structure followed by a variable
+length
+.Vt sockcred
+structure, defined in
 .In sys/socket.h
 as follows:
-.Bd -literal
+.Bd -literal -offset indent
 struct sockcred {
-       pid_t   sc_pid;                 /* process id */
-       uid_t   sc_uid;                 /* real user id */
-       uid_t   sc_euid;                /* effective user id */
-       gid_t   sc_gid;                 /* real group id */
-       gid_t   sc_egid;                /* effective group id */
-       int     sc_ngroups;             /* number of supplemental groups */
-       gid_t   sc_groups[1];           /* variable length */
+        pid_t   sc_pid;         /* process id */
+        uid_t   sc_uid;         /* real user id */
+        uid_t   sc_euid;        /* effective user id */
+        gid_t   sc_gid;         /* real group id */
+        gid_t   sc_egid;        /* effective group id */
+        int     sc_ngroups;     /* number of supplemental groups */
+        gid_t   sc_groups[1];   /* variable length */
 };
 .Ed
 .Pp
@@ -221,22 +231,26 @@
 or
 .Xr bind 2 .
 The returned structure is
-.Bd -literal
+.Bd -literal -offset indent
 struct unpcbid {
-       pid_t unp_pid;                  /* process id */
-       uid_t unp_euid;                 /* effective user id */
-       gid_t unp_egid;                 /* effective group id */
+        pid_t unp_pid;          /* process id */
+        uid_t unp_euid;         /* effective user id */
+        gid_t unp_egid;         /* effective group id */
 };
 .Ed
+.Pp
 as defined in
 .In sys/un.h .
 .Pp
 The
 .Fn SOCKCREDSIZE
-macro computes the size of the sockcred structure for a specified number
-of groups.
-The cmsghdr fields have the following values:
-.Bd -literal
+macro computes the size of the
+.Vt sockcred
+structure for a specified number of groups.
+The
+.Vt cmsghdr
+fields have the following values:
+.Bd -literal -offset indent
 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 cmsg_level = SOL_SOCKET
 cmsg_type = SCM_CREDS
@@ -251,17 +265,16 @@
 memset(&addr, 0, sizeof(addr));
 addr.sun_family = AF_LOCAL;
 if (strlen(pathname) >= sizeof(addr.sun_path))
-       goto too_long;
+        goto too_long;
 strncpy(addr.sun_path, pathname, sizeof(addr.sun_path));
 ret = bind(s, (const struct sockaddr *)&addr, SUN_LEN(&addr));
 if (ret != 0)
-       goto bind_failed;
+        goto bind_failed;
 \&...
-
 .Ed
 .Sh COMPATIBILITY
 The
-.Ar sun_len
+.Fa sun_len
 field exists only in system derived from 4.4BSD.
 On systems which don't have the
 .Fn SUN_LEN
@@ -292,6 +305,6 @@
 .Pq see Pa /usr/share/doc/reference/ref3/sockets-advanced
 .Sh HISTORY
 The
-.Ar sc_pid
+.Fa sc_pid
 field was introduced in
 .Nx 8.0 .