CS(3)	C LIBRARY FUNCTIONS	CS(3)

NAME

cs - connect stream ipc support

SYNOPSIS

#include <cs.h>
-lcs -last

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 cssend and csrecv.

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 csdaemon background fork -- 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 csopen 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:

int csopen(const char* path, int flags)

Open a unique connection to the process that created the connect stream path. The other process must do a csrecv to complete the rendezvous. The connection file descriptor is returned, -1 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

char* cspath(int fd)

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

int cspoll(int nfds, fd_set* rd, fd_set* wr, long ms)

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

FD_NEW(fd_set* set)

Initialize set with no elements.

FD_SET(int fd, fd_set* set)

Add fd to set.

FD_CLR(int fd, fd_set* set)

Remove fd from set.

FD_TST(int fd, fd_set* set)

Return non-zero if fd is a member of set.

int csrecv(int fd, CSID* id, int* fds, int nfds)

Receive up to nfds file descriptors from the stream fd and place them in the array pointed to by fds. The number of received file descriptors is returned, -1 on error. csrecv is used under two circumstances: the first is to complete a rendezvous on a connect stream initiated by a csopen in another process; the second is to receive file descriptors on any stream initiated by a cssend in another process. For local streams id->hid is set to 0 and id->pid, id->uid, and id->gid are set to the process id, user id and group id of the sending process. For remote streams id->hid 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.

int cssend(int fd, int* fds, int nfds)

Send nfds file descriptors pointed to by fds on the stream fd. 0 is returned on success, -1 on error. csrecv is used on the other side of fd to receive the file descriptors. cssend may return before csrecv completes on the other side.

The following routines provide portable interfaces for server related operations.

unsigned long csaddr(char* name, int cache)

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

int csdaemon()

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

int csfdmax()

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

unsigned long csinet(char* path, unsigned short* port, int* prot)

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

char* csname()

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

int csnote(char* name, CSSTAT* sp)

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

char* csntoa(unsigned long addr)

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

int csstat(char* name, CSSTAT* sp)

Return status information in sp for the host name. The information is updated by the system status demon ssd(8) using csnote. Updates are on average every CS_STAT_FREQ 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 CS_STAT_DOWN seconds old. 0 is returned on success, -1 on error. CSSTAT contains the following members:

long up

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

int load

The 1 minute system load average times 100.

unsigned long idle

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

int users

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

int pctusr

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

int pctsys

The percentage of CPU time used by the system itself. The cpu idle time is 100-(pctusr+pctsys).

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 cssend is pending to a hung server until after the server has been killed. The latter can only happen if the server hangs after the cssend request has been initiated.

On some systems the cspoll 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 IPPORT_USERRESERVED [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 0 for cscreat then the system generates a port number, usually below IPPORT_USERRESERVED.

SEE ALSO

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