head	1.3;
access;
symbols
	RELENG_8_4:1.3.0.2
	RELENG_9_1_0_RELEASE:1.1.16.1.4.2
	RELENG_9_1:1.1.16.1.0.4
	RELENG_9_1_BP:1.1.16.1
	RELENG_8_3_0_RELEASE:1.1.10.1.8.1
	RELENG_8_3:1.1.10.1.0.8
	RELENG_8_3_BP:1.1.10.1
	RELENG_9_0_0_RELEASE:1.1.16.1.2.1
	RELENG_9_0:1.1.16.1.0.2
	RELENG_9_0_BP:1.1.16.1
	RELENG_9:1.1.0.16
	RELENG_9_BP:1.1
	RELENG_7_4_0_RELEASE:1.1.14.1
	RELENG_8_2_0_RELEASE:1.1.10.1.6.1
	RELENG_7_4:1.1.0.14
	RELENG_7_4_BP:1.1
	RELENG_8_2:1.1.10.1.0.6
	RELENG_8_2_BP:1.1.10.1
	RELENG_8_1_0_RELEASE:1.1.10.1.4.1
	RELENG_8_1:1.1.10.1.0.4
	RELENG_8_1_BP:1.1.10.1
	RELENG_7_3_0_RELEASE:1.1.12.1
	RELENG_7_3:1.1.0.12
	RELENG_7_3_BP:1.1
	RELENG_8_0_0_RELEASE:1.1.10.1.2.1
	RELENG_8_0:1.1.10.1.0.2
	RELENG_8_0_BP:1.1.10.1
	RELENG_8:1.1.0.10
	RELENG_8_BP:1.1
	RELENG_7_2_0_RELEASE:1.1.8.1
	RELENG_7_2:1.1.0.8
	RELENG_7_2_BP:1.1
	RELENG_7_1_0_RELEASE:1.1.6.1
	RELENG_7_1:1.1.0.6
	RELENG_7_1_BP:1.1
	RELENG_7_0_0_RELEASE:1.1
	RELENG_7_0:1.1.0.4
	RELENG_7_0_BP:1.1
	RELENG_7:1.1.0.2
	RELENG_7_BP:1.1;
locks; strict;
comment	@# @;


1.3
date	2013.02.12.00.34.59;	author svnexp;	state Exp;
branches
	1.3.2.1;
next	1.2;

1.2
date	2012.11.17.01.53.57;	author svnexp;	state Exp;
branches;
next	1.1;

1.1
date	2006.05.29.18.40.55;	author maxim;	state Exp;
branches
	1.1.2.1
	1.1.6.1
	1.1.8.1
	1.1.10.1
	1.1.12.1
	1.1.14.1
	1.1.16.1;
next	;

1.3.2.1
date	2013.02.12.00.34.59;	author svnexp;	state dead;
branches;
next	1.3.2.2;

1.3.2.2
date	2013.03.28.13.05.53;	author svnexp;	state Exp;
branches;
next	;

1.1.2.1
date	2012.11.17.08.08.08;	author svnexp;	state Exp;
branches;
next	;

1.1.6.1
date	2008.11.25.02.59.29;	author kensmith;	state Exp;
branches;
next	;

1.1.8.1
date	2009.04.15.03.14.26;	author kensmith;	state Exp;
branches;
next	;

1.1.10.1
date	2009.08.03.08.13.06;	author kensmith;	state Exp;
branches
	1.1.10.1.2.1
	1.1.10.1.4.1
	1.1.10.1.6.1
	1.1.10.1.8.1;
next	1.1.10.2;

1.1.10.2
date	2012.11.17.10.37.12;	author svnexp;	state Exp;
branches;
next	1.1.10.3;

1.1.10.3
date	2013.04.29.22.21.42;	author svnexp;	state Exp;
branches;
next	;

1.1.10.1.2.1
date	2009.10.25.01.10.29;	author kensmith;	state Exp;
branches;
next	;

1.1.10.1.4.1
date	2010.06.14.02.09.06;	author kensmith;	state Exp;
branches;
next	;

1.1.10.1.6.1
date	2010.12.21.17.09.25;	author kensmith;	state Exp;
branches;
next	;

1.1.10.1.8.1
date	2012.03.03.06.15.13;	author kensmith;	state Exp;
branches;
next	1.1.10.1.8.2;

1.1.10.1.8.2
date	2012.11.17.08.25.46;	author svnexp;	state Exp;
branches;
next	;

1.1.12.1
date	2010.02.10.00.26.20;	author kensmith;	state Exp;
branches;
next	;

1.1.14.1
date	2010.12.21.17.10.29;	author kensmith;	state Exp;
branches;
next	1.1.14.2;

1.1.14.2
date	2012.11.17.08.17.39;	author svnexp;	state Exp;
branches;
next	;

1.1.16.1
date	2011.09.23.00.51.37;	author kensmith;	state Exp;
branches
	1.1.16.1.2.1
	1.1.16.1.4.1;
next	1.1.16.2;

1.1.16.2
date	2012.11.17.11.37.31;	author svnexp;	state Exp;
branches;
next	1.1.16.3;

1.1.16.3
date	2013.04.29.22.04.49;	author svnexp;	state Exp;
branches;
next	;

1.1.16.1.2.1
date	2011.11.11.04.20.22;	author kensmith;	state Exp;
branches;
next	1.1.16.1.2.2;

1.1.16.1.2.2
date	2012.11.17.08.37.27;	author svnexp;	state Exp;
branches;
next	;

1.1.16.1.4.1
date	2012.08.05.23.54.33;	author kensmith;	state Exp;
branches;
next	1.1.16.1.4.2;

1.1.16.1.4.2
date	2012.11.17.08.48.19;	author svnexp;	state Exp;
branches;
next	;


desc
@@


1.3
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/246670
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@$FreeBSD: head/tools/regression/sockets/unix_cmsg/README 246670 2013-02-11 12:56:23Z pluknet $

About unix_cmsg
===============

This program is a collection of regression tests for ancillary data
(control information) for PF_LOCAL sockets (local domain or Unix domain
sockets).  There are tests for stream and datagram sockets.

Usually each test does following steps: creates Server, forks Client,
Client sends something to Server, Server verifies whether everything is
correct in received message(s).

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 that
check credentials can give correct results for wrong implementation.

It is better to run this program by a user that belongs to more
than 16 groups.

Available options
=================

usage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno]

 Options are:
  -d            Output debugging information
  -h            Output the help message and exit
  -n num        Number of messages to send
  -s size       Specify size of data for IPC
  -t type       Specify socket type (stream, dgram) for tests
  -z value      Do not send data in a message (bit 0x1), do not send
                data array associated with a cmsghdr structure (bit 0x2)
  testno        Run one test by its number (require the -t option)

Description
===========

If Client sends something to Server, then it sends 5 messages by default.
Number of messages can be changed in the -n command line option.  Number
of messages will be given as N in the following descriptions.

If Client sends something to Server, then it sends some data (few bytes)
in each message by default.  The size of this data can be changed by the -s
command line option.  The "-s 0" command line option means, that Client will
send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced
by the msg_iov field from struct msghdr{}.  The "-z 1" or "-z 3" command line
option means, that Client will send zero bytes represented by the NULL value
in the msg_iov field from struct msghdr{}.

If Client sends some ancillary data object, then this ancillary data object
always has associated data array by default.  The "-z 2" or "-z 3" option
means, that Client will not send associated data array if possible.

For SOCK_STREAM sockets:
-----------------------

 1: Sending, receiving cmsgcred

    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.

 2: Receiving sockcred (listening socket)

    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket option for it.  Client connects to Server two times, each time
    it sends N messages.  Server accepts two connections and receives N
    messages from each connection.  The first message from each connection
    should have SCM_CREDS ancillary data object followed by struct sockcred{},
    next messages from the same connection should not have ancillary data.

 3: Receiving sockcred (accepted socket)

    Client connects to Server.  Server accepts connection and sets the
    LOCAL_CREDS socket option for just accepted socket.  Client sends N
    messages to Server.  Server should receive N messages, the first
    message should have SCM_CREDS ancillary data object followed by
    struct sockcred{}, next messages should not have ancillary data.

 4: Sending cmsgcred, receiving sockcred

    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket  option for it.  Client connects to Server and sends N messages
    with SCM_CREDS ancillary data object.  Server should receive N messages,
    the first message should have SCM_CREDS ancillary data object followed
    by struct sockcred{}, each of next messages should have SCM_CREDS
    ancillary data object followed by struct cmsgcred{}.

 5: Sending, receiving timeval

    Client connects to Server and sends message with SCM_TIMESTAMP ancillary
    data object.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 6: Sending, receiving bintime

    Client connects to Server and sends message with SCM_BINTIME ancillary
    data object.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 7: Checking cmsghdr.cmsg_len

    Client connects to Server and tries to send several messages with
    SCM_CREDS ancillary data object that has wrong cmsg_len field in its
    struct cmsghdr{}.  All these attempts should fail, since cmsg_len
    in all requests is less than CMSG_LEN(0).

 8: Check LOCAL_PEERCRED socket option

    This test does not use ancillary data, but can be implemented here.
    Client connects to Server.  Both Client and Server verify that
    credentials of the peer are correct using LOCAL_PEERCRED socket option.

For SOCK_DGRAM sockets:
----------------------

 1: Sending, receiving cmsgcred

    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.

 2: Receiving sockcred

    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages to Server.  Server should receive N
    messages, each message should have SCM_CREDS ancillary data object
    followed by struct sockcred{}.

 3: Sending cmsgcred, receiving sockcred

    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages with SCM_CREDS ancillary data object
    to Server.  Server should receive N messages, the first message should
    have SCM_CREDS ancillary data object followed by struct sockcred{},
    each of next messages should have SCM_CREDS ancillary data object
    followed by struct cmsgcred{}.

 4: Sending, receiving timeval

    Client sends one message with SCM_TIMESTAMP ancillary data object
    to Server.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 5: Sending, receiving bintime

    Client sends one message with SCM_BINTIME ancillary data object
    to Server.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 6: Checking cmsghdr.cmsg_len

    Client tries to send Server several messages with SCM_CREDS ancillary
    data object that has wrong cmsg_len field in its struct cmsghdr{}.
    All these attempts should fail, since cmsg_len in all requests is less
    than CMSG_LEN(0).

- Andrey Simonenko
andreysimonenko@@users.sourceforge.net
@


1.3.2.1
log
@file README was added on branch RELENG_8_4 on 2013-03-28 13:05:53 +0000
@
text
@d1 160
@


1.3.2.2
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/248810
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@a0 127
$FreeBSD: releng/8.4/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $

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
@


1.2
log
@Switching exporter and resync
@
text
@d1 1
a1 1
$FreeBSD: head/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
d4 1
a4 1
================
d6 7
a12 8
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.
d15 5
a19 2
(eg. nobody:nogroup) and set SUID and SGID bits, else some tests
can give correct results for wrong implementation.
d24 1
a24 19
-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.
d26 28
a53 2
Description of tests
====================
d60 20
a79 26
    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.
d83 31
a113 13
    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{}.
d120 3
a122 5
    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.
d126 4
a129 5
    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.
d132 26
a157 12
 
    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{}.
d160 1
a160 1
simon@@comsys.ntu-kpi.kiev.ua
@


1.1
log
@o Add a collection of regression tests for ancillary (control)
data passing for unix domain sockets, stream and datagram.

There are 15 tests:

Test/Type of socket					STREAM	DGRAM
----------------------------------------------------------------------
Sending, receiving cmsgcred				   1      6
Receiving sockcred (listening socket has LOCAL_CREDS)	   2      n/a
Receiving sockcred (accepted socket has LOCAL_CREDS)	   3      n/a
Receiving sockcred					   n/a    7
Sending cmsgcred, receiving sockcred			   4      8
Sending, receiving timestamp				   5      9
Sending, receiving cmsgcred (no control data)		   10     13
Sending cmsgcred, receiving sockcred (no control data)	   11     14
Sending, receiving timestamp (no control data)		   12     15

Currently we pass 8 tests.  All the rest marked as TODO.

PR:		kern/90800
Submitted by:	Andrey Simonenko
@
text
@d1 1
a1 1
$FreeBSD$
@


1.1.2.1
log
@Switch importer
@
text
@d1 1
a1 1
$FreeBSD: stable/7/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.16.1
log
@SVN rev 225736 on 2011-09-23 00:51:37Z by kensmith

Copy head to stable/9 as part of 9.0-RELEASE release cycle.

Approved by:	re (implicit)
@
text
@@


1.1.16.2
log
@## SVN ##
## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/ 242902
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ## r242902 | dteske | 2012-11-11 23:29:45 +0000 (Sun, 11 Nov 2012) | 10 lines
## SVN ##
## SVN ## Fix a regression introduced by SVN r211417 that saw the breakage of a feature
## SVN ## documented in usr.sbin/sysinstall/help/shortcuts.hlp (reproduced below):
## SVN ##
## SVN ## If /usr/sbin/sysinstall is linked to another filename, say
## SVN ## `/usr/local/bin/configPackages', then the basename will be used
## SVN ## as an implicit command name.
## SVN ##
## SVN ## Reviewed by:	adrian (co-mentor)
## SVN ## Approved by:	adrian (co-mentor)
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ##
@
text
@d1 1
a1 1
$FreeBSD: stable/9/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.16.3
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/250076
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@d1 1
a1 1
$FreeBSD: stable/9/tools/regression/sockets/unix_cmsg/README 250076 2013-04-29 21:30:04Z pluknet $
d4 1
a4 1
===============
d6 8
a13 7
This program is a collection of regression tests for ancillary data
(control information) for PF_LOCAL sockets (local domain or Unix domain
sockets).  There are tests for stream and datagram sockets.

Usually each test does following steps: creates Server, forks Client,
Client sends something to Server, Server verifies whether everything is
correct in received message(s).
d16 2
a17 5
(eg. nobody:nogroup) and set SUID and SGID bits, else some tests that
check credentials can give correct results for wrong implementation.

It is better to run this program by a user that belongs to more
than 16 groups.
d22 19
a40 1
usage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno]
d42 2
a43 28
 Options are:
  -d            Output debugging information
  -h            Output the help message and exit
  -n num        Number of messages to send
  -s size       Specify size of data for IPC
  -t type       Specify socket type (stream, dgram) for tests
  -z value      Do not send data in a message (bit 0x1), do not send
                data array associated with a cmsghdr structure (bit 0x2)
  testno        Run one test by its number (require the -t option)

Description
===========

If Client sends something to Server, then it sends 5 messages by default.
Number of messages can be changed in the -n command line option.  Number
of messages will be given as N in the following descriptions.

If Client sends something to Server, then it sends some data (few bytes)
in each message by default.  The size of this data can be changed by the -s
command line option.  The "-s 0" command line option means, that Client will
send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced
by the msg_iov field from struct msghdr{}.  The "-z 1" or "-z 3" command line
option means, that Client will send zero bytes represented by the NULL value
in the msg_iov field from struct msghdr{}.

If Client sends some ancillary data object, then this ancillary data object
always has associated data array by default.  The "-z 2" or "-z 3" option
means, that Client will not send associated data array if possible.
d50 26
a75 20
    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.

 2: Receiving sockcred (listening socket)

    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket option for it.  Client connects to Server two times, each time
    it sends N messages.  Server accepts two connections and receives N
    messages from each connection.  The first message from each connection
    should have SCM_CREDS ancillary data object followed by struct sockcred{},
    next messages from the same connection should not have ancillary data.

 3: Receiving sockcred (accepted socket)

    Client connects to Server.  Server accepts connection and sets the
    LOCAL_CREDS socket option for just accepted socket.  Client sends N
    messages to Server.  Server should receive N messages, the first
    message should have SCM_CREDS ancillary data object followed by
    struct sockcred{}, next messages should not have ancillary data.
d79 13
a91 31
    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket  option for it.  Client connects to Server and sends N messages
    with SCM_CREDS ancillary data object.  Server should receive N messages,
    the first message should have SCM_CREDS ancillary data object followed
    by struct sockcred{}, each of next messages should have SCM_CREDS
    ancillary data object followed by struct cmsgcred{}.

 5: Sending, receiving timeval

    Client connects to Server and sends message with SCM_TIMESTAMP ancillary
    data object.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 6: Sending, receiving bintime

    Client connects to Server and sends message with SCM_BINTIME ancillary
    data object.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 7: Checking cmsghdr.cmsg_len

    Client connects to Server and tries to send several messages with
    SCM_CREDS ancillary data object that has wrong cmsg_len field in its
    struct cmsghdr{}.  All these attempts should fail, since cmsg_len
    in all requests is less than CMSG_LEN(0).

 8: Check LOCAL_PEERCRED socket option

    This test does not use ancillary data, but can be implemented here.
    Client connects to Server.  Both Client and Server verify that
    credentials of the peer are correct using LOCAL_PEERCRED socket option.
d98 5
a102 3
    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
d106 5
a110 4
    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages to Server.  Server should receive N
    messages, each message should have SCM_CREDS ancillary data object
    followed by struct sockcred{}.
d113 12
a124 26

    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages with SCM_CREDS ancillary data object
    to Server.  Server should receive N messages, the first message should
    have SCM_CREDS ancillary data object followed by struct sockcred{},
    each of next messages should have SCM_CREDS ancillary data object
    followed by struct cmsgcred{}.

 4: Sending, receiving timeval

    Client sends one message with SCM_TIMESTAMP ancillary data object
    to Server.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 5: Sending, receiving bintime

    Client sends one message with SCM_BINTIME ancillary data object
    to Server.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 6: Checking cmsghdr.cmsg_len

    Client tries to send Server several messages with SCM_CREDS ancillary
    data object that has wrong cmsg_len field in its struct cmsghdr{}.
    All these attempts should fail, since cmsg_len in all requests is less
    than CMSG_LEN(0).
d127 1
a127 1
andreysimonenko@@users.sourceforge.net
@


1.1.16.1.4.1
log
@SVN rev 239080 on 2012-08-05 23:54:33Z by kensmith

Copy stable/9 to releng/9.1 as part of the 9.1-RELEASE release process.

Approved by:	re (implicit)
@
text
@@


1.1.16.1.4.2
log
@Switch importer
@
text
@d1 1
a1 1
$FreeBSD: releng/9.1/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.16.1.2.1
log
@SVN rev 227445 on 2011-11-11 04:20:22Z by kensmith

Copy stable/9 to releng/9.0 as part of the FreeBSD 9.0-RELEASE release
cycle.

Approved by:	re (implicit)
@
text
@@


1.1.16.1.2.2
log
@Switch importer
@
text
@d1 1
a1 1
$FreeBSD: releng/9.0/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.14.1
log
@SVN rev 216618 on 2010-12-21 17:10:29Z by kensmith

Copy stable/7 to releng/7.4 in preparation for FreeBSD-7.4 release.

Approved by:	re (implicit)
@
text
@@


1.1.14.2
log
@Switch importer
@
text
@d1 1
a1 1
$FreeBSD: releng/7.4/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.12.1
log
@SVN rev 203736 on 2010-02-10 00:26:20Z by kensmith

Copy stable/7 to releng/7.3 as part of the 7.3-RELEASE process.

Approved by:	re (implicit)
@
text
@@


1.1.10.1
log
@SVN rev 196045 on 2009-08-03 08:13:06Z by kensmith

Copy head to stable/8 as part of 8.0 Release cycle.

Approved by:	re (Implicit)
@
text
@@


1.1.10.2
log
@## SVN ##
## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/ 242909
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ## r242909 | dim | 2012-11-12 07:47:19 +0000 (Mon, 12 Nov 2012) | 20 lines
## SVN ##
## SVN ## MFC r242625:
## SVN ##
## SVN ## Remove duplicate const specifiers in many drivers (I hope I got all of
## SVN ## them, please let me know if not).  Most of these are of the form:
## SVN ##
## SVN ## static const struct bzzt_type {
## SVN ##       [...list of members...]
## SVN ## } const bzzt_devs[] = {
## SVN ##       [...list of initializers...]
## SVN ## };
## SVN ##
## SVN ## The second const is unnecessary, as arrays cannot be modified anyway,
## SVN ## and if the elements are const, the whole thing is const automatically
## SVN ## (e.g. it is placed in .rodata).
## SVN ##
## SVN ## I have verified this does not change the binary output of a full kernel
## SVN ## build (except for build timestamps embedded in the object files).
## SVN ##
## SVN ## Reviewed by:	yongari, marius
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ##
@
text
@d1 1
a1 1
$FreeBSD: stable/8/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.10.3
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/250077
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@d1 1
a1 1
$FreeBSD: stable/8/tools/regression/sockets/unix_cmsg/README 250077 2013-04-29 21:33:36Z pluknet $
d4 1
a4 1
===============
d6 8
a13 7
This program is a collection of regression tests for ancillary data
(control information) for PF_LOCAL sockets (local domain or Unix domain
sockets).  There are tests for stream and datagram sockets.

Usually each test does following steps: creates Server, forks Client,
Client sends something to Server, Server verifies whether everything is
correct in received message(s).
d16 2
a17 5
(eg. nobody:nogroup) and set SUID and SGID bits, else some tests that
check credentials can give correct results for wrong implementation.

It is better to run this program by a user that belongs to more
than 16 groups.
d22 19
a40 1
usage: unix_cmsg [-dh] [-n num] [-s size] [-t type] [-z value] [testno]
d42 2
a43 28
 Options are:
  -d            Output debugging information
  -h            Output the help message and exit
  -n num        Number of messages to send
  -s size       Specify size of data for IPC
  -t type       Specify socket type (stream, dgram) for tests
  -z value      Do not send data in a message (bit 0x1), do not send
                data array associated with a cmsghdr structure (bit 0x2)
  testno        Run one test by its number (require the -t option)

Description
===========

If Client sends something to Server, then it sends 5 messages by default.
Number of messages can be changed in the -n command line option.  Number
of messages will be given as N in the following descriptions.

If Client sends something to Server, then it sends some data (few bytes)
in each message by default.  The size of this data can be changed by the -s
command line option.  The "-s 0" command line option means, that Client will
send zero bytes represented by { NULL, 0 } value of struct iovec{}, referenced
by the msg_iov field from struct msghdr{}.  The "-z 1" or "-z 3" command line
option means, that Client will send zero bytes represented by the NULL value
in the msg_iov field from struct msghdr{}.

If Client sends some ancillary data object, then this ancillary data object
always has associated data array by default.  The "-z 2" or "-z 3" option
means, that Client will not send associated data array if possible.
d50 26
a75 20
    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.

 2: Receiving sockcred (listening socket)

    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket option for it.  Client connects to Server two times, each time
    it sends N messages.  Server accepts two connections and receives N
    messages from each connection.  The first message from each connection
    should have SCM_CREDS ancillary data object followed by struct sockcred{},
    next messages from the same connection should not have ancillary data.

 3: Receiving sockcred (accepted socket)

    Client connects to Server.  Server accepts connection and sets the
    LOCAL_CREDS socket option for just accepted socket.  Client sends N
    messages to Server.  Server should receive N messages, the first
    message should have SCM_CREDS ancillary data object followed by
    struct sockcred{}, next messages should not have ancillary data.
d79 13
a91 31
    Server creates a listening stream socket and sets the LOCAL_CREDS
    socket  option for it.  Client connects to Server and sends N messages
    with SCM_CREDS ancillary data object.  Server should receive N messages,
    the first message should have SCM_CREDS ancillary data object followed
    by struct sockcred{}, each of next messages should have SCM_CREDS
    ancillary data object followed by struct cmsgcred{}.

 5: Sending, receiving timeval

    Client connects to Server and sends message with SCM_TIMESTAMP ancillary
    data object.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 6: Sending, receiving bintime

    Client connects to Server and sends message with SCM_BINTIME ancillary
    data object.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 7: Checking cmsghdr.cmsg_len

    Client connects to Server and tries to send several messages with
    SCM_CREDS ancillary data object that has wrong cmsg_len field in its
    struct cmsghdr{}.  All these attempts should fail, since cmsg_len
    in all requests is less than CMSG_LEN(0).

 8: Check LOCAL_PEERCRED socket option

    This test does not use ancillary data, but can be implemented here.
    Client connects to Server.  Both Client and Server verify that
    credentials of the peer are correct using LOCAL_PEERCRED socket option.
d98 5
a102 3
    Client connects to Server and sends N messages with SCM_CREDS ancillary
    data object.  Server should receive N messages, each message should
    have SCM_CREDS ancillary data object followed by struct cmsgcred{}.
d106 5
a110 4
    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages to Server.  Server should receive N
    messages, each message should have SCM_CREDS ancillary data object
    followed by struct sockcred{}.
d113 12
a124 26

    Server creates datagram socket and sets the LOCAL_CREDS socket option
    for it.  Client sends N messages with SCM_CREDS ancillary data object
    to Server.  Server should receive N messages, the first message should
    have SCM_CREDS ancillary data object followed by struct sockcred{},
    each of next messages should have SCM_CREDS ancillary data object
    followed by struct cmsgcred{}.

 4: Sending, receiving timeval

    Client sends one message with SCM_TIMESTAMP ancillary data object
    to Server.  Server should receive one message with SCM_TIMESTAMP
    ancillary data object followed by struct timeval{}.

 5: Sending, receiving bintime

    Client sends one message with SCM_BINTIME ancillary data object
    to Server.  Server should receive one message with SCM_BINTIME
    ancillary data object followed by struct bintime{}.

 6: Checking cmsghdr.cmsg_len

    Client tries to send Server several messages with SCM_CREDS ancillary
    data object that has wrong cmsg_len field in its struct cmsghdr{}.
    All these attempts should fail, since cmsg_len in all requests is less
    than CMSG_LEN(0).
d127 1
a127 1
andreysimonenko@@users.sourceforge.net
@


1.1.10.1.8.1
log
@SVN rev 232438 on 2012-03-03 06:15:13Z by kensmith

Copy stable/8 to releng/8.3 as part of 8.3-RELEASE release cycle.

Approved by:	re (implicit)
@
text
@@


1.1.10.1.8.2
log
@Switch importer
@
text
@d1 1
a1 1
$FreeBSD: releng/8.3/tools/regression/sockets/unix_cmsg/README 159045 2006-05-29 18:40:55Z maxim $
@


1.1.10.1.6.1
log
@SVN rev 216617 on 2010-12-21 17:09:25Z by kensmith

Copy stable/8 to releng/8.2 in preparation for FreeBSD-8.2 release.

Approved by:	re (implicit)
@
text
@@


1.1.10.1.4.1
log
@SVN rev 209145 on 2010-06-14 02:09:06Z by kensmith

Copy stable/8 to releng/8.1 in preparation for 8.1-RC1.

Approved by:	re (implicit)
@
text
@@


1.1.10.1.2.1
log
@SVN rev 198460 on 2009-10-25 01:10:29Z by kensmith

Copy stable/8 to releng/8.0 as part of 8.0-RELEASE release procedure.

Approved by:	re (implicit)
@
text
@@


1.1.8.1
log
@SVN rev 191087 on 2009-04-15 03:14:26Z by kensmith

Create releng/7.2 from stable/7 in preparation for 7.2-RELEASE.

Approved by:	re (implicit)
@
text
@@


1.1.6.1
log
@SVN rev 185281 on 2008-11-25 02:59:29Z by kensmith

Create releng/7.1 in preparation for moving into RC phase of 7.1 release
cycle.

Approved by:	re (implicit)
@
text
@@

