$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