CS(3)

NAME
cs - connect stream ipc support

SYNOPSIS

DESCRIPTION
The cs routines support local and remote connect streams in the file system name space. This is a traditional alternative to the service/port database schemes used by the BSD derivatives and the streams-based alternatives in 10th edition and s5r4. The interface presented here is the same for all systems that support sockets or streams.

Connect stream files allow unrelated processes to rendezvous. A server first creates a connect stream. Each client open of the connect stream received by the server presents a unique bi-directional pipe connection between the client and server.

Connect streams may be either local or remote. Local connections support file descriptor exchange via and

Connect stream names are of the form /dev/proto/host/service[/options proto is fdp for local streams and tcp or udp for remote streams. host is either a host name or an internet n.n.n.n address. local names the local host and share names any host on the local network that is running the service. service is either a service name or an integer port number. The options are / separated and further qualify the connect stream:

user[=uid]
    restricts the connection to the current [uid] user

group[=gid]
    restricts the connection to the current [gid] group

other
    (default) specifies no user or group restrictions.

local
    causes a share service to be instantiated on the local host if it is not already running

remote
    causes the host address to be interpreted as remote -- mainly used to debug remote authentication

slave
    used service instantiation to disable the background -- used by master servers to preserve the parent/child relationship

Other options are service dependent and are used to name different instantiations of the same service.

Most servers reside in the directory lib/cs/proto/service. server is the name of the server executable. The file hosts lists the hosts on which the service can be automatically started (see below). The first available host will be used. The special host name share is expanded to a list of the local network file servers. If hosts is omitted then share is assumed.

The basic routines are:

Open a unique connection to the process that created the connect stream The other process must do a to complete the rendezvous. The connection file descriptor is returned, on error. If the service is not running and the server and hosts files corresponding to the connect stream are located then the service HERE

Return a pointer to an equivalent pathname for the open file descriptor

Poll the file descriptors through in for read events (data available for or and for write events or possible). may be if read(write) events are not of interest. The number of file descriptors matching the requested events is returned, and and are modified to reflect the matched file descriptors. will timeout after milliseconds. If is then will block until one of the requested events occurs. is returned if no events occurred before the timeout, on error. variables are manipulated by the following functions:

    Initialize
        with no elements.

    Add to

    Remove
        from

    Return non-zero if
        is a member of

Receive up to file descriptors from the stream and place them in the array pointed to by The number of received file descriptors is returned, on error. is used under two circumstances: the first is to complete a rendezvous on a connect stream initiated by a in another process; the second is to receive file descriptors on any stream initiated by a in another process. For local streams is set to and and are set to the process id, user id and group id of the sending process. For remote streams is set to the internet address of the sending process and the remaining elements are undefined. In any event, only the uid and gid can currently be trusted.

Send file descriptors pointed to by on the stream is returned on success, on error. is used on the other side of to receive the file descriptors. may return before completes on the other side.

The following routines provide portable interfaces for server related operations.

Return the internet address for the host If is greater than zero then intermediate information will be cached for subsequent requests. If is less than zero then the previous value is retained. Otherwise caching is turned off. is returned on error.

Fork into the background and drop the controlling terminal. is returned on success, on error.

Return the per-process maximum number of open file descriptors. At least will be returned.

Parse the internet address and optional port number from the path name and return the address. If is non-zero then it is set to point to the port number. If omitted the default port number is is returned on error. If is non-zero then it is set to one of or depending on the protocol.

Return a pointer to the local host name. A non-null pointer is always returned.

Note a change to the host status for This routine is used by the system status demon ssd(8) and is the write counterpart of See below for a description of the members. The current working directory must be and the calling process must own the local host status file. is returned on success, on error.

Return the n.n.n.n string address for

Return status information in for the host The information is updated by the system status demon ssd(8) using Updates are on average every seconds. The update frequency is randomized to avoid synchronized update spikes from multiple hosts. A host is considered down if its status information is more than seconds old. is returned on success, on error. contains the following members:

    System uptime in seconds.
        If negative then the system has been down for at least seconds.

    The 1 minute system load average times 100.

    The minimum idle time in seconds for all users logged into the system.
        Keyboard strokes and mouse movement are included in the calculation.

    The number of users that have been active within the last 24 hours.

    The percentage of CPU time used by user and low priority processes.

    The percentage of CPU time used by the system itself.
        The cpu idle time is

CAVEATS
Mounting streams in the file system and sending file descriptors between processes is tricky business. Most systems can be coaxed to panic with just the right sequence of events. This library has been written to narrow the panic windows, but there is still opportunity for crashes. For example (unless you are at a trade show): on s5r4, don't unlink a connect stream path while a server has it open; and on BSD don't kill a client while a is pending to a hung server until after the server has been killed. The latter can only happen if the server hangs after the request has been initiated.

On some systems the millisecond timeout is rounded up to the nearest second.

For remote connect stream path names the service component, if it is not registered in the service table, is hashed to generate a 16 bit TCP port number above [5000]. The hashed port number for a given service will be the same on all systems. It is possible for two distinct paths to generate the same port number, but this is also the case for independently administered service tables. However, if port number clashes become a problem then a name service will be transparently slipped in to provide a 1-1 mapping between path names and port numbers. If service is for then the system generates a port number, usually below

SEE ALSO
ss(1), libx(3), ssd(8)