tools/regression/sockets/unix_cmsg/README

   1 $FreeBSD$
   2
   3 About unix_cmsg
   4 ================
   5
   6 This program is a collection of regression tests for ancillary (control)
   7 data for PF_LOCAL sockets (local domain or Unix domain sockets).  There
   8 are tests for stream and datagram sockets.
   9
  10 Usually each test does following steps: create Server, fork Client,
  11 Client sends something to Server, Server verifies if everything
  12 is correct in received message.  Sometimes Client sends several
  13 messages to Server.
  14
  15 It 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
  17 can give correct results for wrong implementation.
  18
  19 Available 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
  42 Description of tests
  43 ====================
  44
  45 For 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
  93 For 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
 127 simon@comsys.ntu-kpi.kiev.ua