1$FreeBSD: head/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
| 1$FreeBSD: head/tools/regression/sockets/unix_cmsg/README 246670 2013-02-11 12:56:23Z pluknet $
|
2 3About unix_cmsg
| 2 3About unix_cmsg
|
4================
| 4===============
|
5
| 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.
| 6This program is a collection of regression tests for ancillary data 7(control information) for PF_LOCAL sockets (local domain or Unix domain 8sockets). There are tests for stream and datagram sockets.
|
9
| 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.
| 10Usually each test does following steps: creates Server, forks Client, 11Client sends something to Server, Server verifies whether everything is 12correct in received message(s).
|
14 15It is better to change the owner of unix_cmsg to some safe user
| 13 14It 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.
| 15(eg. nobody:nogroup) and set SUID and SGID bits, else some tests that 16check credentials can give correct results for wrong implementation.
|
18
| 17
|
| 18It is better to run this program by a user that belongs to more 19than 16 groups. 20
|
19Available options 20================= 21
| 21Available options 22================= 23
|
22-d Output debugging information, values of different fields of 23 received messages, etc. Will produce many lines of information.
| 24usage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno]
|
24
| 25
|
25-h Output help message and exit.
| 26 Options are: 27 -d Output debugging information 28 -h Output the help message and exit 29 -n num Number of messages to send 30 -s size Specify size of data for IPC 31 -t type Specify socket type (stream, dgram) for tests 32 -z value Do not send data in a message (bit 0x1), do not send 33 data array associated with a cmsghdr structure (bit 0x2) 34 testno Run one test by its number (require the -t option)
|
26
| 35
|
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.
| 36Description 37===========
|
31
| 38
|
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).
| 39If Client sends something to Server, then it sends 5 messages by default. 40Number of messages can be changed in the -n command line option. Number 41of messages will be given as N in the following descriptions.
|
36
| 42
|
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.
| 43If Client sends something to Server, then it sends some data (few bytes) 44in each message by default. The size of this data can be changed by the -s 45command line option. The "-s 0" command line option means, that Client will 46send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced 47by the msg_iov field from struct msghdr{}. The "-z 1" or "-z 3" command line 48option means, that Client will send zero bytes represented by the NULL value 49in the msg_iov field from struct msghdr{}.
|
41
| 50
|
42Description of tests 43====================
| 51If Client sends some ancillary data object, then this ancillary data object 52always has associated data array by default. The "-z 2" or "-z 3" option 53means, that Client will not send associated data array if possible.
|
44 45For SOCK_STREAM sockets: 46----------------------- 47 48 1: Sending, receiving cmsgcred 49
| 54 55For SOCK_STREAM sockets: 56----------------------- 57 58 1: Sending, receiving cmsgcred 59
|
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.
| 60 Client connects to Server and sends N messages with SCM_CREDS ancillary 61 data object. Server should receive N messages, each message should 62 have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
|
55
| 63
|
56 2: Receiving sockcred (listening socket has LOCAL_CREDS)
| 64 2: Receiving sockcred (listening socket)
|
57
| 65
|
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.
| 66 Server creates a listening stream socket and sets the LOCAL_CREDS 67 socket option for it. Client connects to Server two times, each time 68 it sends N messages. Server accepts two connections and receives N 69 messages from each connection. The first message from each connection 70 should have SCM_CREDS ancillary data object followed by struct sockcred{}, 71 next messages from the same connection should not have ancillary data.
|
65
| 72
|
66 3: Receiving sockcred (accepted socket has LOCAL_CREDS)
| 73 3: Receiving sockcred (accepted socket)
|
67
| 74
|
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.
| 75 Client connects to Server. Server accepts connection and sets the 76 LOCAL_CREDS socket option for just accepted socket. Client sends N 77 messages to Server. Server should receive N messages, the first 78 message should have SCM_CREDS ancillary data object followed by 79 struct sockcred{}, next messages should not have ancillary data.
|
76 77 4: Sending cmsgcred, receiving sockcred 78
| 80 81 4: Sending cmsgcred, receiving sockcred 82
|
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.
| 83 Server creates a listening stream socket and sets the LOCAL_CREDS 84 socket option for it. Client connects to Server and sends N messages 85 with SCM_CREDS ancillary data object. Server should receive N messages, 86 the first message should have SCM_CREDS ancillary data object followed 87 by struct sockcred{}, each of next messages should have SCM_CREDS 88 ancillary data object followed by struct cmsgcred{}.
|
85
| 89
|
86 5: Sending, receiving timestamp
| 90 5: Sending, receiving timeval
|
87
| 91
|
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 Client connects to Server and sends message with SCM_TIMESTAMP ancillary 93 data object. Server should receive one message with SCM_TIMESTAMP 94 ancillary data object followed by struct timeval{}.
|
92
| 95
|
| 96 6: Sending, receiving bintime 97 98 Client connects to Server and sends message with SCM_BINTIME ancillary 99 data object. Server should receive one message with SCM_BINTIME 100 ancillary data object followed by struct bintime{}. 101 102 7: Checking cmsghdr.cmsg_len 103 104 Client connects to Server and tries to send several messages with 105 SCM_CREDS ancillary data object that has wrong cmsg_len field in its 106 struct cmsghdr{}. All these attempts should fail, since cmsg_len 107 in all requests is less than CMSG_LEN(0). 108 109 8: Check LOCAL_PEERCRED socket option 110 111 This test does not use ancillary data, but can be implemented here. 112 Client connects to Server. Both Client and Server verify that 113 credentials of the peer are correct using LOCAL_PEERCRED socket option. 114
|
93For SOCK_DGRAM sockets: 94---------------------- 95 96 1: Sending, receiving cmsgcred 97
| 115For SOCK_DGRAM sockets: 116---------------------- 117 118 1: Sending, receiving cmsgcred 119
|
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.
| 120 Client connects to Server and sends N messages with SCM_CREDS ancillary 121 data object. Server should receive N messages, each message should 122 have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
|
103 104 2: Receiving sockcred 105
| 123 124 2: Receiving sockcred 125
|
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.
| 126 Server creates datagram socket and sets the LOCAL_CREDS socket option 127 for it. Client sends N messages to Server. Server should receive N 128 messages, each message should have SCM_CREDS ancillary data object 129 followed by struct sockcred{}.
|
111 112 3: Sending cmsgcred, receiving sockcred
| 130 131 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
| 132
|
120 4: Sending, receiving timestamp
| 133 Server creates datagram socket and sets the LOCAL_CREDS socket option 134 for it. Client sends N messages with SCM_CREDS ancillary data object 135 to Server. Server should receive N messages, the first message should 136 have SCM_CREDS ancillary data object followed by struct sockcred{}, 137 each of next messages should have SCM_CREDS ancillary data object 138 followed by struct cmsgcred{}.
|
121
| 139
|
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{}.
| 140 4: Sending, receiving timeval
|
125
| 141
|
| 142 Client sends one message with SCM_TIMESTAMP ancillary data object 143 to Server. Server should receive one message with SCM_TIMESTAMP 144 ancillary data object followed by struct timeval{}. 145 146 5: Sending, receiving bintime 147 148 Client sends one message with SCM_BINTIME ancillary data object 149 to Server. Server should receive one message with SCM_BINTIME 150 ancillary data object followed by struct bintime{}. 151 152 6: Checking cmsghdr.cmsg_len 153 154 Client tries to send Server several messages with SCM_CREDS ancillary 155 data object that has wrong cmsg_len field in its struct cmsghdr{}. 156 All these attempts should fail, since cmsg_len in all requests is less 157 than CMSG_LEN(0). 158
|
126- Andrey Simonenko
| 159- Andrey Simonenko
|
127simon@comsys.ntu-kpi.kiev.ua
| 160andreysimonenko@users.sourceforge.net
|
| |