man/: Terminology consistency reforms (n, size, length)

Use 'length' for the lenght of a string. Use 'n' for the number of elements. Use 'size' for the number of bytes. (And in wide-character string functions, 'size' also refers to the number of wide characters.) The change is quite large, and I might have made some mistakes. But overall, this should improve consistency in use of these terms. Signed-off-by: Alejandro Colomar <alx@kernel.org>
author: Alejandro Colomar <alx@kernel.org> 2024-11-17 18:47:53 +0100
committer: Alejandro Colomar <alx@kernel.org> 2024-11-17 21:51:23 +0100
commit: 18e7c4597c4e72fa5210c7887273e363c456c9ee (patch)
tree: 97cfd22e731a4c859ae71783d70943ff72e6cb60 /man/man7
parent: 8fc6fdd8291d906e58a175b5e1b20da680aaeb4a (diff)
download: man-pages-18e7c4597c4e.tar.gz
7 files changed, 65 insertions, 65 deletions
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index b270f3c99e..676d8194da 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -280,7 +280,7 @@ The fields of the
 structure are as follows:
 .TP
 .I event_len
-This is the length of the data for the current event and the offset
+This is the size of the data for the current event and the offset
 to the next event in the buffer.
 Unless the group identifies filesystem objects by file handles, the value of
 .I event_len
@@ -288,7 +288,7 @@ is always
 .BR FAN_EVENT_METADATA_LEN .
 For a group that identifies filesystem objects by file handles,
 .I event_len
-also includes the variable length file identifier records.
+also includes the variable size file identifier records.
 .TP
 .I vers
 This field holds a version number for the structure.
@@ -303,7 +303,7 @@ fanotify file descriptor.
 This field is not used.
 .TP
 .I metadata_len
-This is the length of the structure.
+This is the size of the structure.
 The field was introduced to facilitate the implementation of
 optional headers per event type.
 No such optional headers exist in the current implementation.
@@ -588,7 +588,7 @@ so monitoring different filesystem instances that report zero
 with the same fanotify group is not supported.
 .TP
 .I handle
-This field contains a variable-length structure of type
+This field contains a variable-size structure of type
 .IR "struct file_handle" .
 It is an opaque handle that corresponds to a specified object on a
 filesystem as returned by
@@ -704,33 +704,33 @@ fanotify event metadata returned by a
 .BR read (2)
 from an fanotify file descriptor:
 .TP
-.B FAN_EVENT_OK(meta, len)
-This macro checks the remaining length
-.I len
+.B FAN_EVENT_OK(meta, size)
+This macro checks the remaining size
+.I size
 of the buffer
 .I meta
-against the length of the metadata structure and the
+against the size of the metadata structure and the
 .I event_len
 field of the first metadata structure in the buffer.
 .TP
-.B FAN_EVENT_NEXT(meta, len)
-This macro uses the length indicated in the
+.B FAN_EVENT_NEXT(meta, size)
+This macro uses the size indicated in the
 .I event_len
 field of the metadata structure pointed to by
 .I meta
 to calculate the address of the next metadata structure that follows
 .IR meta .
-.I len
+.I size
 is the number of bytes of metadata that currently remain in the buffer.
 The macro returns a pointer to the next metadata structure that follows
 .IR meta ,
 and reduces
-.I len
+.I size
 by the number of bytes in the metadata structure that
 has been skipped over (i.e., it subtracts
 .I meta\->event_len
 from
-.IR len ).
+.IR size ).
 .P
 In addition, there is:
 .TP
@@ -1002,7 +1002,7 @@ capability is set for programs executed by unprivileged users.
 If a call to
 .BR read (2)
 processes multiple events from the fanotify queue and an error occurs,
-the return value will be the total length of the events successfully
+the return value will be the total size of the events successfully
 copied to the user-space buffer before the error occurred.
 The return value will not be \-1, and
 .I errno
@@ -1066,7 +1066,7 @@ handle_events(int fd)
 {
     const struct fanotify_event_metadata *metadata;
     struct fanotify_event_metadata buf[200];
-    ssize_t len;
+    ssize_t size;
     char path[PATH_MAX];
     ssize_t path_len;
     char procfd_path[PATH_MAX];
@@ -1078,15 +1078,15 @@ handle_events(int fd)
 \&
         /* Read some events. */
 \&
-        len = read(fd, buf, sizeof(buf));
-        if (len == \-1 && errno != EAGAIN) {
+        size = read(fd, buf, sizeof(buf));
+        if (size == \-1 && errno != EAGAIN) {
             perror("read");
             exit(EXIT_FAILURE);
         }
 \&
         /* Check if end of available data reached. */
 \&
-        if (len <= 0)
+        if (size <= 0)
             break;
 \&
         /* Point to the first event in the buffer. */
@@ -1095,7 +1095,7 @@ handle_events(int fd)
 \&
         /* Loop over all events in the buffer. */
 \&
-        while (FAN_EVENT_OK(metadata, len)) {
+        while (FAN_EVENT_OK(metadata, size)) {
 \&
             /* Check that run\-time and compile\-time structures match. */
 \&
@@ -1149,7 +1149,7 @@ handle_events(int fd)
 \&
             /* Advance to next event. */
 \&
-            metadata = FAN_EVENT_NEXT(metadata, len);
+            metadata = FAN_EVENT_NEXT(metadata, size);
         }
     }
 }
@@ -1322,7 +1322,7 @@ int
 main(int argc, char *argv[])
 {
     int fd, ret, event_fd, mount_fd;
-    ssize_t len, path_len;
+    ssize_t size, path_len;
     char path[PATH_MAX];
     char procfd_path[PATH_MAX];
     char events_buf[BUF_SIZE];
@@ -1367,8 +1367,8 @@ main(int argc, char *argv[])
 \&
     /* Read events from the event queue into a buffer. */
 \&
-    len = read(fd, events_buf, sizeof(events_buf));
-    if (len == \-1 && errno != EAGAIN) {
+    size = read(fd, events_buf, sizeof(events_buf));
+    if (size == \-1 && errno != EAGAIN) {
         perror("read");
         exit(EXIT_FAILURE);
     }
@@ -1376,8 +1376,8 @@ main(int argc, char *argv[])
     /* Process all events within the buffer. */
 \&
     for (metadata = (struct fanotify_event_metadata *) events_buf;
-            FAN_EVENT_OK(metadata, len);
-            metadata = FAN_EVENT_NEXT(metadata, len)) {
+            FAN_EVENT_OK(metadata, size);
+            metadata = FAN_EVENT_NEXT(metadata, size)) {
         fid = (struct fanotify_event_info_fid *) (metadata + 1);
         file_handle = (struct file_handle *) fid\->handle;
 \&
diff --git a/man/man7/inotify.7 b/man/man7/inotify.7
index 8ce99a6d18..05dbae20b0 100644
--- a/man/man7/inotify.7
+++ b/man/man7/inotify.7
@@ -134,10 +134,10 @@ The
 field counts all of the bytes in
 .IR name ,
 including the null bytes;
-the length of each
+the size of each
 .I inotify_event
 structure is thus
-.IR "sizeof(struct inotify_event)+len" .
+.IR "sizeof(struct inotify_event)+size" .
 .P
 The behavior when the buffer given to
 .BR read (2)
@@ -910,7 +910,7 @@ Listening for events stopped.
 \&
 /* Read all available inotify events from the file descriptor \[aq]fd\[aq].
    wd is the table of watch descriptors for the directories in argv.
-   argc is the length of wd and argv.
+   argc is the size of wd and argv.
    argv is the list of watched directories.
    Entry 0 of wd and argv is unused. */
 \&
@@ -926,7 +926,7 @@ handle_events(int fd, int *wd, int argc, char* argv[])
     char buf[4096]
         __attribute__ ((aligned(__alignof__(struct inotify_event))));
     const struct inotify_event *event;
-    ssize_t len;
+    ssize_t size;
 \&
     /* Loop while events can be read from inotify file descriptor. */
 \&
@@ -934,8 +934,8 @@ handle_events(int fd, int *wd, int argc, char* argv[])
 \&
         /* Read some events. */
 \&
-        len = read(fd, buf, sizeof(buf));
-        if (len == \-1 && errno != EAGAIN) {
+        size = read(fd, buf, sizeof(buf));
+        if (size == \-1 && errno != EAGAIN) {
             perror("read");
             exit(EXIT_FAILURE);
         }
@@ -944,12 +944,12 @@ handle_events(int fd, int *wd, int argc, char* argv[])
            it returns \-1 with errno set to EAGAIN. In that case,
            we exit the loop. */
 \&
-        if (len <= 0)
+        if (size <= 0)
             break;
 \&
         /* Loop over all events in the buffer. */
 \&
-        for (char *ptr = buf; ptr < buf + len;
+        for (char *ptr = buf; ptr < buf + size;
                 ptr += sizeof(struct inotify_event) + event\->len) {
 \&
             event = (const struct inotify_event *) ptr;
diff --git a/man/man7/netlink.7 b/man/man7/netlink.7
index 4198bf157c..c29ec4582b 100644
--- a/man/man7/netlink.7
+++ b/man/man7/netlink.7
@@ -170,7 +170,7 @@ the payload follows.
 .in +4n
 .EX
 struct nlmsghdr {
-    __u32 nlmsg_len;    /* Length of message including header */
+    __u32 nlmsg_len;    /* Size of message including header */
     __u16 nlmsg_type;   /* Type of message content */
     __u16 nlmsg_flags;  /* Additional flags */
     __u32 nlmsg_seq;    /* Sequence number */
@@ -203,7 +203,7 @@ struct nlmsgerr {
      * unless NETLINK_CAP_ACK was set
      * or the ACK indicates success (error == 0).
      * For example Generic Netlink message with attributes.
-     * message length is aligned with NLMSG_ALIGN()
+     * message size is aligned with NLMSG_ALIGN()
      */
     /*
      * followed by TLVs defined in enum nlmsgerr_attrs
@@ -566,7 +566,7 @@ And the last example is about reading netlink message.
 .P
 .in +4n
 .EX
-int len;
+int size;
 /* 8192 to avoid message truncation on platforms with
    page size > 4096 */
 struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)];
@@ -576,10 +576,10 @@ struct msghdr msg;
 struct nlmsghdr *nh;
 \&
 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
-len = recvmsg(fd, &msg, 0);
+size = recvmsg(fd, &msg, 0);
 \&
-for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
-     nh = NLMSG_NEXT (nh, len)) {
+for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, size);
+     nh = NLMSG_NEXT (nh, size)) {
     /* The end of multipart message */
     if (nh\->nlmsg_type == NLMSG_DONE)
         return;
diff --git a/man/man7/packet.7 b/man/man7/packet.7
index 2763275f7c..dc1144848e 100644
--- a/man/man7/packet.7
+++ b/man/man7/packet.7
@@ -109,7 +109,7 @@ flag is passed to
 .BR recv (2),
 or
 .BR recvfrom (2),
-the real length of the packet on the wire is always returned,
+the real size of the packet on the wire is always returned,
 even when it is longer than the buffer.
 .SS Address types
 The
@@ -124,7 +124,7 @@ struct sockaddr_ll {
     int            sll_ifindex;  /* Interface number */
     unsigned short sll_hatype;   /* ARP hardware type */
     unsigned char  sll_pkttype;  /* Packet type */
-    unsigned char  sll_halen;    /* Length of address */
+    unsigned char  sll_halen;    /* Size of address */
     unsigned char  sll_addr[8];  /* Physical\-layer address */
 };
 .EE
@@ -169,7 +169,7 @@ These types make sense only for receiving.
 .I sll_addr
 .TQ
 .I sll_halen
-contain the physical-layer (e.g., IEEE 802.3) address and its length.
+contain the physical-layer (e.g., IEEE 802.3) address and its size.
 The exact interpretation depends on the device.
 .P
 When you send packets, it is enough to specify
@@ -210,7 +210,7 @@ structure as argument:
 struct packet_mreq {
     int            mr_ifindex;    /* interface index */
     unsigned short mr_type;       /* action */
-    unsigned short mr_alen;       /* address length */
+    unsigned short mr_alen;       /* address size */
     unsigned char  mr_address[8]; /* physical\-layer address */
 };
 .EE
@@ -255,8 +255,8 @@ It is defined as
 .EX
 struct tpacket_auxdata {
     __u32 tp_status;
-    __u32 tp_len;      /* packet length */
-    __u32 tp_snaplen;  /* captured length */
+    __u32 tp_len;      /* packet size */
+    __u32 tp_snaplen;  /* captured size */
     __u16 tp_mac;
     __u16 tp_net;
     __u16 tp_vlan_tci;
@@ -569,7 +569,7 @@ header for a IEEE 802.3 frame.
 When
 .B ETH_P_802_3
 is specified as protocol for sending the kernel creates the
-802.3 frame and fills out the length field; the user has to supply the LLC
+802.3 frame and fills out the size field; the user has to supply the LLC
 header to get a fully conforming packet.
 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
 fields; instead they are supplied to the user as protocol
@@ -647,7 +647,7 @@ which is 16 bytes and describes the system limit for a network interface name.
 This means the names of network devices longer than 14 bytes
 will be truncated to fit into
 .IR spkt_device .
-All these lengths include the terminating null byte (\[aq]\[rs]0\[aq])).
+All these sizes include the terminating null byte (\[aq]\[rs]0\[aq])).
 .P
 Issues from this with old code typically show up with
 very long interface names used by the
diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index 33fb2702f0..39428841ba 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -166,7 +166,7 @@ The attribute reported in answer to this request is
 The payload associated with this attribute is the pathname to which
 the socket was bound (a sequence of bytes up to
 .B UNIX_PATH_MAX
-length).
+size).
 .TP
 .B UDIAG_SHOW_VFS
 The attribute reported in answer to this request is
@@ -232,7 +232,7 @@ The fields of this structure are as follows:
 .I udiag_rqueue
 For listening sockets:
 the number of pending connections.
-The length of the array associated with the
+The size of the array associated with the
 .B UNIX_DIAG_ICONS
 response attribute is equal to this value.
 .IP
@@ -241,7 +241,7 @@ the amount of data in incoming queue.
 .TP
 .I udiag_wqueue
 For listening sockets:
-the backlog length which equals to the value passed as the second argument to
+the backlog size which equals to the value passed as the second argument to
 .BR listen (2).
 .IP
 For established sockets:
@@ -555,7 +555,7 @@ the amount of data in the incoming queue.
 .TP
 .I idiag_wqueue
 For listening sockets:
-the backlog length.
+the backlog size.
 .IP
 For other sockets:
 the amount of memory available for sending.
@@ -681,9 +681,9 @@ send_query(int fd)
 }
 \&
 static int
-print_diag(const struct unix_diag_msg *diag, unsigned int len)
+print_diag(const struct unix_diag_msg *diag, unsigned int size)
 {
-    if (len < NLMSG_LENGTH(sizeof(*diag))) {
+    if (size < NLMSG_LENGTH(sizeof(*diag))) {
         fputs("short response\[rs]n", stderr);
         return \-1;
     }
@@ -692,7 +692,7 @@ print_diag(const struct unix_diag_msg *diag, unsigned int len)
         return \-1;
     }
 \&
-    unsigned int rta_len = len \- NLMSG_LENGTH(sizeof(*diag));
+    unsigned int rta_len = size \- NLMSG_LENGTH(sizeof(*diag));
     unsigned int peer = 0;
     size_t path_len = 0;
     char path[sizeof(((struct sockaddr_un *) 0)\->sun_path) + 1];
diff --git a/man/man7/socket.7 b/man/man7/socket.7
index 5b45e4cdf3..2527b4003b 100644
--- a/man/man7/socket.7
+++ b/man/man7/socket.7
@@ -313,10 +313,10 @@ or an extended BPF
 program to the socket for use as a filter of incoming packets.
 A packet will be dropped if the filter program returns zero.
 If the filter program returns a
-nonzero value which is less than the packet's data length,
-the packet will be truncated to the length returned.
+nonzero value which is less than the packet's data size,
+the packet will be truncated to the size returned.
 If the value returned by the filter is greater than or equal to the
-packet's data length, the packet is allowed to proceed unmodified.
+packet's data size, the packet is allowed to proceed unmodified.
 .IP
 The argument for
 .B SO_ATTACH_FILTER
@@ -402,9 +402,9 @@ TCP support is available since Linux 4.6.
 Bind this socket to a particular device like \[lq]eth0\[rq],
 as specified in the passed interface name.
 If the
-name is an empty string or the option length is zero, the socket device
+name is an empty string or the option size is zero, the socket device
 binding is removed.
-The passed option is a variable-length null-terminated
+The passed option is a variable-size null-terminated
 interface name string with the maximum size of
 .BR IFNAMSIZ .
 If a socket is bound to an interface,
@@ -1132,7 +1132,7 @@ caused by external network events.
 Maximum number of packets in the global input queue.
 .TP
 .I optmem_max
-Maximum length of ancillary data and user control data like the iovecs
+Maximum size of ancillary data and user control data like the iovecs
 per socket.
 .\" netdev_fastroute is not documented because it is experimental
 .SS Ioctls
diff --git a/man/man7/user_namespaces.7 b/man/man7/user_namespaces.7
index 4131d49270..b8a9331f91 100644
--- a/man/man7/user_namespaces.7
+++ b/man/man7/user_namespaces.7
@@ -413,7 +413,7 @@ The specification in each line takes the form of
 three numbers delimited by white space.
 The first two numbers specify the starting user ID in
 each of the two user namespaces.
-The third number specifies the length of the mapped range.
+The third number specifies the size of the mapped range.
 In detail, the fields are interpreted as follows:
 .IP (1) 5
 The start of the range of user IDs in
@@ -446,7 +446,7 @@ to see the mapping of user IDs into the user namespace of the process
 that created this user namespace.
 .RE
 .IP (3)
-The length of the range of user IDs that is mapped between the two
+The size of the range of user IDs that is mapped between the two
 user namespaces.
 .P
 System calls that return user IDs (group IDs)\[em]for example,
@@ -483,7 +483,7 @@ $ \fBcat /proc/$$/uid_map\fP
 This mapping tells us
 that the range starting at user ID 0 in this namespace
 maps to a range starting at 0 in the (nonexistent) parent namespace,
-and the length of the range is the largest 32-bit unsigned integer.
+and the size of the range is the largest 32-bit unsigned integer.
 This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
 This is deliberate:
 .I (uid_t)\~\-1
@@ -1207,7 +1207,7 @@ usage(char *pname)
     fpe("\[rs]n");
     fpe("Map strings for \-M and \-G consist of records of the form:\[rs]n");
     fpe("\[rs]n");
-    fpe("    ID\-inside\-ns   ID\-outside\-ns   len\[rs]n");
+    fpe("    ID\-inside\-ns   ID\-outside\-ns   size\[rs]n");
     fpe("\[rs]n");
     fpe("A map string can contain multiple records, separated"
         " by commas;\[rs]n");
@@ -1222,7 +1222,7 @@ usage(char *pname)
    GID mapping consists of one or more newline\-delimited records
    of the form:
 \&
-       ID_inside\-ns    ID\-outside\-ns   length
+       ID_inside\-ns    ID\-outside\-ns   size
 \&
    Requiring the user to supply a string that contains newlines is
    of course inconvenient for command\-line use. Thus, we permit the
author	Alejandro Colomar <alx@kernel.org>	2024-11-17 18:47:53 +0100
committer	Alejandro Colomar <alx@kernel.org>	2024-11-17 21:51:23 +0100
commit	18e7c4597c4e72fa5210c7887273e363c456c9ee (patch)
tree	97cfd22e731a4c859ae71783d70943ff72e6cb60 /man/man7
parent	8fc6fdd8291d906e58a175b5e1b20da680aaeb4a (diff)
download	man-pages-18e7c4597c4e.tar.gz