Merging upstream version 6.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 87 insertions, 69 deletions

diff --git a/man7/unix.7 b/man7/unix.7
index cfa4188..426a430 100644
--- a/man7/unix.7
+++ b/man7/unix.7
@@ -12,14 +12,14 @@
 .\"     address that can appear in the sockaddr_un structure: pathname,
 .\"     unnamed, and abstract.
 .\"
-.TH UNIX 7 2023-07-15 "Linux man-pages 6.05.01"
+.TH UNIX 7 2024-03-16 "Linux man-pages 6.7"
 .SH NAME
 unix \- sockets for local interprocess communication
 .SH SYNOPSIS
 .nf
 .B #include <sys/socket.h>
 .B #include <sys/un.h>
-.PP
+.P
 .IB unix_socket " = socket(AF_UNIX, type, 0);"
 .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");"
 .fi
@@ -34,7 +34,7 @@ Traditionally, UNIX domain sockets can be either unnamed,
 or bound to a filesystem pathname (marked as being of type socket).
 Linux also supports an abstract namespace which is independent of the
 filesystem.
-.PP
+.P
 Valid socket types in the UNIX domain are:
 .BR SOCK_STREAM ,
 for a stream-oriented socket;
@@ -47,12 +47,12 @@ and (since Linux 2.6.4)
 for a sequenced-packet socket that is connection-oriented,
 preserves message boundaries,
 and delivers messages in the order that they were sent.
-.PP
+.P
 UNIX domain sockets support passing file descriptors or process credentials
 to other processes using ancillary data.
 .SS Address format
 A UNIX domain socket address is represented in the following structure:
-.PP
+.P
 .in +4n
 .EX
 .\" #define UNIX_PATH_MAX    108
@@ -63,7 +63,7 @@ struct sockaddr_un {
 };
 .EE
 .in
-.PP
+.P
 The
 .I sun_family
 field always contains
@@ -71,8 +71,8 @@ field always contains
 On Linux,
 .I sun_path
 is 108 bytes in size; see also BUGS, below.
-.PP
-Various systems calls (for example,
+.P
+Various system calls (for example,
 .BR bind (2),
 .BR connect (2),
 and
@@ -87,7 +87,7 @@ Some other system calls (for example,
 and
 .BR accept (2))
 return an argument of this type.
-.PP
+.P
 Three types of address are distinguished in the
 .I sockaddr_un
 structure:
@@ -186,7 +186,7 @@ or, more simply,
 .I addrlen
 can be specified as
 .IR "sizeof(struct sockaddr_un)" .
-.PP
+.P
 There is some variation in how implementations handle UNIX domain
 socket addresses that do not follow the above rules.
 For example, some (but not all) implementations
@@ -194,7 +194,7 @@ For example, some (but not all) implementations
 .\" is 108 bytes
 append a null terminator if none is present in the supplied
 .IR sun_path .
-.PP
+.P
 When coding portable applications,
 keep in mind that some implementations
 .\" HP-UX
@@ -203,7 +203,7 @@ have
 as short as 92 bytes.
 .\" Modern BSDs generally have 104, Tru64 and AIX have 104,
 .\" Solaris and Irix have 108
-.PP
+.P
 Various system calls
 .RB ( accept (2),
 .BR recvfrom (2),
@@ -227,7 +227,7 @@ In the Linux implementation,
 pathname sockets honor the permissions of the directory they are in.
 Creation of a new socket fails if the process does not have write and
 search (execute) permission on the directory in which the socket is created.
-.PP
+.P
 On Linux,
 connecting to a stream socket object requires write permission on that socket;
 sending a datagram to a datagram socket likewise
@@ -237,13 +237,13 @@ on a socket file, and on some systems (e.g., older BSDs),
 the socket permissions are ignored.
 Portable programs should not rely on
 this feature for security.
-.PP
+.P
 When creating a new socket, the owner and group of the socket file
 are set according to the usual rules.
 The socket file has all permissions enabled,
 other than those that are turned off by the process
 .BR umask (2).
-.PP
+.P
 The owner, group, and permissions of a pathname socket can be changed (using
 .BR chown (2)
 and
@@ -260,10 +260,10 @@ and changing the ownership and permissions of the object (via
 and
 .BR fchmod (2))
 has no effect on the accessibility of the socket.
-.PP
+.P
 Abstract sockets automatically disappear when all open references
 to the socket are closed.
-.PP
+.P
 The abstract socket namespace is a nonportable Linux extension.
 .\"
 .SS Socket options
@@ -331,7 +331,8 @@ This read-only socket option returns the
 credentials of the peer process connected to this socket.
 The returned credentials are those that were in effect at the time
 of the call to
-.BR connect (2)
+.BR connect (2),
+.BR listen (2),
 or
 .BR socketpair (2).
 .IP
@@ -418,7 +419,7 @@ The change to 5 bytes came in Linux 2.3.15.)
 .SS Sockets API
 The following paragraphs describe domain-specific details and
 unsupported features of the sockets API for UNIX domain sockets on Linux.
-.PP
+.P
 UNIX domain sockets do not support the transmission of
 out-of-band data (the
 .B MSG_OOB
@@ -426,12 +427,12 @@ flag for
 .BR send (2)
 and
 .BR recv (2)).
-.PP
+.P
 The
 .BR send (2)
 .B MSG_MORE
 flag is not supported by UNIX domain sockets.
-.PP
+.P
 Before Linux 3.4,
 .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
 the use of
@@ -441,7 +442,7 @@ in the
 argument of
 .BR recv (2)
 was not supported by UNIX domain sockets.
-.PP
+.P
 The
 .B SO_SNDBUF
 socket option does have an effect for UNIX domain sockets, but the
@@ -573,11 +574,11 @@ bytes in the data portion of the ancillary message for this data.
 To receive the security context, the
 .B SO_PASSSEC
 option must be enabled on the socket (see above).
-.PP
+.P
 When sending ancillary data with
 .BR sendmsg (2),
 only one item of each of the above types may be included in the sent message.
-.PP
+.P
 At least one byte of real data should be sent when sending ancillary data.
 On Linux, this is required to successfully send ancillary data over
 a UNIX domain stream socket.
@@ -585,11 +586,11 @@ When sending ancillary data over a UNIX domain datagram socket,
 it is not necessary on Linux to send any accompanying real data.
 However, portable applications should also include at least one byte
 of real data when sending ancillary data over a datagram socket.
-.PP
+.P
 When receiving from a stream socket,
 ancillary data forms a kind of barrier for the received data.
 For example, suppose that the sender transmits as follows:
-.PP
+.P
 .RS
 .PD 0
 .IP (1) 5
@@ -603,7 +604,7 @@ of one byte, with ancillary data.
 of four bytes, with no ancillary data.
 .PD
 .RE
-.PP
+.P
 Suppose that the receiver now performs
 .BR recvmsg (2)
 calls each with a buffer size of 20 bytes.
@@ -612,7 +613,7 @@ along with the ancillary data sent by the second
 .BR sendmsg (2)
 call.
 The next call will receive the remaining four bytes of data.
-.PP
+.P
 If the space allocated for receiving incoming ancillary data is too small
 then the ancillary data is truncated to the number of headers
 that will fit in the supplied buffer (or, in the case of an
@@ -639,14 +640,14 @@ The following
 calls return information in
 .IR value .
 The correct syntax is:
-.PP
+.P
 .RS
 .nf
 .BI int " value";
 .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");"
 .fi
 .RE
-.PP
+.P
 .I ioctl_type
 can be:
 .TP
@@ -800,7 +801,7 @@ by sending each file descriptor with
 and then closing the file descriptor so that it was not accounted against the
 .B RLIMIT_NOFILE
 resource limit.
-.PP
+.P
 Other errors can be generated by the generic socket layer or
 by the filesystem while generating a filesystem socket object.
 See the appropriate manual pages for more information.
@@ -818,7 +819,7 @@ longer needed (using
 The usual UNIX close-behind semantics apply; the socket can be unlinked
 at any time and will be finally removed from the filesystem when the last
 reference to it is closed.
-.PP
+.P
 To pass file descriptors or credentials over a
 .B SOCK_STREAM
 socket, you must
@@ -827,12 +828,12 @@ send or receive at least one byte of nonancillary data in the same
 or
 .BR recvmsg (2)
 call.
-.PP
+.P
 UNIX domain stream sockets do not support the notion of out-of-band data.
 .\"
 .SH BUGS
 When binding a socket to an address,
-Linux is one of the implementations that appends a null terminator
+Linux is one of the implementations that append a null terminator
 if none is supplied in
 .IR sun_path .
 In most cases this is unproblematic:
@@ -855,7 +856,7 @@ then the returned address structure
 .I won't
 have a null terminator in
 .IR sun_path .
-.PP
+.P
 In addition, some implementations
 .\" i.e., traditional BSD
 don't require a null terminator when binding a socket (the
@@ -865,12 +866,12 @@ argument is used to determine the length of
 and when the socket address is retrieved on these implementations,
 there is no null terminator in
 .IR sun_path .
-.PP
+.P
 Applications that retrieve socket addresses can (portably) code
 to handle the possibility that there is no null terminator in
 .I sun_path
 by respecting the fact that the number of valid bytes in the pathname is:
-.PP
+.P
 .in +4n
 .EX
 strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
@@ -886,7 +887,7 @@ strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
 .\" 2012-04-18
 .\"
 .\" FIXME . Track http://austingroupbugs.net/view.php?id=561
-.PP
+.P
 Alternatively, an application can retrieve
 the socket address by allocating a buffer of size
 .I "sizeof(struct sockaddr_un)+1"
@@ -898,7 +899,7 @@ as
 and the extra zero byte ensures that there will be
 a null terminator for the string returned in
 .IR sun_path :
-.PP
+.P
 .in +4n
 .EX
 void *addrp;
@@ -915,7 +916,7 @@ if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1)
 printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path);
 .EE
 .in
-.PP
+.P
 This sort of messiness can be avoided if it is guaranteed
 that the applications that
 .I create
@@ -933,7 +934,7 @@ The server sends back a message containing the sum of the client's integers.
 The client prints the sum and exits.
 The server waits for the next client to connect.
 To stop the server, the client is called with the command-line argument "DOWN".
-.PP
+.P
 The following output was recorded while running the server in the background
 and repeatedly executing the client.
 Execution of the server program ends when it receives the "DOWN" command.
@@ -954,6 +955,7 @@ $
 .in
 .SS Program source
 \&
+.\" SRC BEGIN (connection.h)
 .EX
 /*
  * File connection.h
@@ -961,7 +963,11 @@ $
 \&
 #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket"
 #define BUFFER_SIZE 12
-\&
+.EE
+.\" SRC END
+.P
+.\" SRC BEGIN (server.c)
+.EX
 /*
  * File server.c
  */
@@ -972,18 +978,20 @@ $
 #include <sys/socket.h>
 #include <sys/un.h>
 #include <unistd.h>
+\&
 #include "connection.h"
 \&
 int
-main(int argc, char *argv[])
+main(void)
 {
-    struct sockaddr_un name;
-    int down_flag = 0;
-    int ret;
-    int connection_socket;
-    int data_socket;
-    int result;
-    char buffer[BUFFER_SIZE];
+    int                 down_flag = 0;
+    int                 ret;
+    int                 connection_socket;
+    int                 data_socket;
+    int                 result;
+    ssize_t             r, w;
+    struct sockaddr_un  name;
+    char                buffer[BUFFER_SIZE];
 \&
     /* Create local socket. */
 \&
@@ -1042,8 +1050,8 @@ main(int argc, char *argv[])
 \&
             /* Wait for next data packet. */
 \&
-            ret = read(data_socket, buffer, sizeof(buffer));
-            if (ret == \-1) {
+            r = read(data_socket, buffer, sizeof(buffer));
+            if (r == \-1) {
                 perror("read");
                 exit(EXIT_FAILURE);
             }
@@ -1056,13 +1064,17 @@ main(int argc, char *argv[])
 \&
             if (!strncmp(buffer, "DOWN", sizeof(buffer))) {
                 down_flag = 1;
-                break;
+                continue;
             }
 \&
             if (!strncmp(buffer, "END", sizeof(buffer))) {
                 break;
             }
 \&
+            if (down_flag) {
+                continue;
+            }
+\&
             /* Add received summand. */
 \&
             result += atoi(buffer);
@@ -1071,8 +1083,8 @@ main(int argc, char *argv[])
         /* Send result. */
 \&
         sprintf(buffer, "%d", result);
-        ret = write(data_socket, buffer, sizeof(buffer));
-        if (ret == \-1) {
+        w = write(data_socket, buffer, sizeof(buffer));
+        if (w == \-1) {
             perror("write");
             exit(EXIT_FAILURE);
         }
@@ -1096,27 +1108,32 @@ main(int argc, char *argv[])
 \&
     exit(EXIT_SUCCESS);
 }
-\&
+.EE
+.\" SRC END
+.P
+.\" SRC BEGIN (client.c)
+.EX
 /*
  * File client.c
  */
 \&
-#include <errno.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/socket.h>
 #include <sys/un.h>
 #include <unistd.h>
+\&
 #include "connection.h"
 \&
 int
 main(int argc, char *argv[])
 {
-    struct sockaddr_un addr;
-    int ret;
-    int data_socket;
-    char buffer[BUFFER_SIZE];
+    int                 ret;
+    int                 data_socket;
+    ssize_t             r, w;
+    struct sockaddr_un  addr;
+    char                buffer[BUFFER_SIZE];
 \&
     /* Create local socket. */
 \&
@@ -1148,9 +1165,9 @@ main(int argc, char *argv[])
 \&
     /* Send arguments. */
 \&
-    for (size_t i = 1; i < argc; ++i) {
-        ret = write(data_socket, argv[i], strlen(argv[i]) + 1);
-        if (ret == \-1) {
+    for (int i = 1; i < argc; ++i) {
+        w = write(data_socket, argv[i], strlen(argv[i]) + 1);
+        if (w == \-1) {
             perror("write");
             break;
         }
@@ -1159,16 +1176,16 @@ main(int argc, char *argv[])
     /* Request result. */
 \&
     strcpy(buffer, "END");
-    ret = write(data_socket, buffer, strlen(buffer) + 1);
-    if (ret == \-1) {
+    w = write(data_socket, buffer, strlen(buffer) + 1);
+    if (w == \-1) {
         perror("write");
         exit(EXIT_FAILURE);
     }
 \&
     /* Receive result. */
 \&
-    ret = read(data_socket, buffer, sizeof(buffer));
-    if (ret == \-1) {
+    r = read(data_socket, buffer, sizeof(buffer));
+    if (r == \-1) {
         perror("read");
         exit(EXIT_FAILURE);
     }
@@ -1186,7 +1203,8 @@ main(int argc, char *argv[])
     exit(EXIT_SUCCESS);
 }
 .EE
-.PP
+.\" SRC END
+.P
 For examples of the use of
 .BR SCM_RIGHTS ,
 see