1$FreeBSD$
2
3About unix_cmsg
4================
5
6This program is a collection of regression tests for ancillary (control)
7data for PF_LOCAL sockets (local domain or Unix domain sockets).  There
8are tests for stream and datagram sockets.
9
10Usually each test does following steps: create Server, fork Client,
11Client sends something to Server, Server verifies if everything
12is correct in received message.  Sometimes Client sends several
13messages to Server.
14
15It is better to change the owner of unix_cmsg to some safe user
16(eg. nobody:nogroup) and set SUID and SGID bits, else some tests
17can give correct results for wrong implementation.
18
19Available options
20=================
21
22-d	Output debugging information, values of different fields of
23	received messages, etc.  Will produce many lines of information.
24
25-h	Output help message and exit.
26
27-t <socktype>
28	Run tests only for the given socket type: "stream" or "dgram".
29	With this option it is possible to run only particular test,
30	not all of them.
31
32-z	Do not send real control data if possible.  Struct cmsghdr{}
33	should be followed by real control data.  It is not clear if
34	a sender should give control data in all cases (this is not
35	documented and an arbitrary application can choose anything).
36
37	At least for PF_LOCAL sockets' control messages with types
38	SCM_CREDS and SCM_TIMESTAMP the kernel does not need any
39	control data.  This option allow to not send real control data
40	for SCM_CREDS and SCM_TIMESTAMP control messages.
41
42Description of tests
43====================
44
45For SOCK_STREAM sockets:
46-----------------------
47
48 1: Sending, receiving cmsgcred
49
50    Client connects to Server and sends two messages with data and
51    control message with SCM_CREDS type to Server.  Server should
52    receive two messages, in both messages there should be data and
53    control message with SCM_CREDS type followed by struct cmsgcred{}
54    and this structure should contain correct information.
55
56 2: Receiving sockcred (listening socket has LOCAL_CREDS)
57
58    Server creates listen socket and set socket option LOCAL_CREDS
59    for it.  Client connects to Server and sends two messages with data
60    to Server.  Server should receive two messages, in first message
61    there should be data and control message with SCM_CREDS type followed
62    by struct sockcred{} and this structure should contain correct
63    information, in second message there should be data and no control
64    message.
65
66 3: Receiving sockcred (accepted socket has LOCAL_CREDS)
67
68    Client connects to Server and sends two messages with data.  Server
69    accepts connection and set socket option LOCAL_CREDS for just accepted
70    socket (here synchronization is used, to allow Client to see just set
71    flag on Server's socket before sending messages to Server).  Server
72    should receive two messages, in first message there should be data and
73    control message with SOCK_CRED type followed by struct sockcred{} and
74    this structure should contain correct information, in second message
75    there should be data and no control message.
76
77 4: Sending cmsgcred, receiving sockcred
78
79    Server creates listen socket and set socket option LOCAL_CREDS
80    for it.  Client connects to Server and sends one message with data
81    and control message with SCM_CREDS type to Server.  Server should
82    receive one message with data and control message with SCM_CREDS type
83    followed by struct sockcred{} and this structure should contain
84    correct information.
85
86 5: Sending, receiving timestamp
87
88    Client connects to Server and sends message with data and control
89    message with SCM_TIMESTAMP type to Server.  Server should receive
90    message with data and control message with SCM_TIMESTAMP type
91    followed by struct timeval{}.
92
93For SOCK_DGRAM sockets:
94----------------------
95
96 1: Sending, receiving cmsgcred
97
98    Client sends to Server two messages with data and control message
99    with SCM_CREDS type to Server.  Server should receive two messages,
100    in both messages there should be data and control message with
101    SCM_CREDS type followed by struct cmsgcred{} and this structure
102    should contain correct information.
103
104 2: Receiving sockcred
105
106    Server creates datagram socket and set socket option LOCAL_CREDS
107    for it.  Client sends two messages with data to Server.  Server should
108    receive two messages, in both messages there should be data and control
109    message with SCM_CREDS type followed by struct sockcred{} and this
110    structure should contain correct information.
111
112 3: Sending cmsgcred, receiving sockcred
113
114    Server creates datagram socket and set socket option LOCAL_CREDS
115    for it.  Client sends one message with data and control message with
116    SOCK_CREDS type to Server.  Server should receive one message with
117    data and control message with SCM_CREDS type followed by struct
118    sockcred{} and this structure should contain correct information.
119
120 4: Sending, receiving timestamp
121
122    Client sends message with data and control message with SCM_TIMESTAMP
123    type to Server.  Server should receive message with data and control
124    message with SCM_TIMESTAMP type followed by struct timeval{}.
125
126- Andrey Simonenko
127simon@comsys.ntu-kpi.kiev.ua
128