diff options
Diffstat (limited to 'tools/regression/sockets/unix_cmsg/README')
| -rw-r--r-- | tools/regression/sockets/unix_cmsg/README | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/tools/regression/sockets/unix_cmsg/README b/tools/regression/sockets/unix_cmsg/README new file mode 100644 index 000000000000..359da438c360 --- /dev/null +++ b/tools/regression/sockets/unix_cmsg/README @@ -0,0 +1,127 @@ +$FreeBSD$ + +About unix_cmsg +================ + +This program is a collection of regression tests for ancillary (control) +data for PF_LOCAL sockets (local domain or Unix domain sockets). There +are tests for stream and datagram sockets. + +Usually each test does following steps: create Server, fork Client, +Client sends something to Server, Server verifies if everything +is correct in received message. Sometimes Client sends several +messages to Server. + +It is better to change the owner of unix_cmsg to some safe user +(eg. nobody:nogroup) and set SUID and SGID bits, else some tests +can give correct results for wrong implementation. + +Available options +================= + +-d Output debugging information, values of different fields of + received messages, etc. Will produce many lines of information. + +-h Output help message and exit. + +-t <socktype> + Run tests only for the given socket type: "stream" or "dgram". + With this option it is possible to run only particular test, + not all of them. + +-z Do not send real control data if possible. Struct cmsghdr{} + should be followed by real control data. It is not clear if + a sender should give control data in all cases (this is not + documented and an arbitrary application can choose anything). + + At least for PF_LOCAL sockets' control messages with types + SCM_CREDS and SCM_TIMESTAMP the kernel does not need any + control data. This option allow to not send real control data + for SCM_CREDS and SCM_TIMESTAMP control messages. + +Description of tests +==================== + +For SOCK_STREAM sockets: +----------------------- + + 1: Sending, receiving cmsgcred + + Client connects to Server and sends two messages with data and + control message with SCM_CREDS type to Server. Server should + receive two messages, in both messages there should be data and + control message with SCM_CREDS type followed by struct cmsgcred{} + and this structure should contain correct information. + + 2: Receiving sockcred (listening socket has LOCAL_CREDS) + + Server creates listen socket and set socket option LOCAL_CREDS + for it. Client connects to Server and sends two messages with data + to Server. Server should receive two messages, in first message + there should be data and control message with SCM_CREDS type followed + by struct sockcred{} and this structure should contain correct + information, in second message there should be data and no control + message. + + 3: Receiving sockcred (accepted socket has LOCAL_CREDS) + + Client connects to Server and sends two messages with data. Server + accepts connection and set socket option LOCAL_CREDS for just accepted + socket (here synchronization is used, to allow Client to see just set + flag on Server's socket before sending messages to Server). Server + should receive two messages, in first message there should be data and + control message with SOCK_CRED type followed by struct sockcred{} and + this structure should contain correct information, in second message + there should be data and no control message. + + 4: Sending cmsgcred, receiving sockcred + + Server creates listen socket and set socket option LOCAL_CREDS + for it. Client connects to Server and sends one message with data + and control message with SCM_CREDS type to Server. Server should + receive one message with data and control message with SCM_CREDS type + followed by struct sockcred{} and this structure should contain + correct information. + + 5: Sending, receiving timestamp + + Client connects to Server and sends message with data and control + message with SCM_TIMESTAMP type to Server. Server should receive + message with data and control message with SCM_TIMESTAMP type + followed by struct timeval{}. + +For SOCK_DGRAM sockets: +---------------------- + + 1: Sending, receiving cmsgcred + + Client sends to Server two messages with data and control message + with SCM_CREDS type to Server. Server should receive two messages, + in both messages there should be data and control message with + SCM_CREDS type followed by struct cmsgcred{} and this structure + should contain correct information. + + 2: Receiving sockcred + + Server creates datagram socket and set socket option LOCAL_CREDS + for it. Client sends two messages with data to Server. Server should + receive two messages, in both messages there should be data and control + message with SCM_CREDS type followed by struct sockcred{} and this + structure should contain correct information. + + 3: Sending cmsgcred, receiving sockcred + + Server creates datagram socket and set socket option LOCAL_CREDS + for it. Client sends one message with data and control message with + SOCK_CREDS type to Server. Server should receive one message with + data and control message with SCM_CREDS type followed by struct + sockcred{} and this structure should contain correct information. + + 4: Sending, receiving timestamp + + Client sends message with data and control message with SCM_TIMESTAMP + type to Server. Server should receive message with data and control + message with SCM_TIMESTAMP type followed by struct timeval{}. + +- Andrey Simonenko +simon@comsys.ntu-kpi.kiev.ua |