|CS(3)||C LIBRARY FUNCTIONS||CS(3)|
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:
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:
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.
Fork into the background and drop the controlling terminal. 0 is returned on success, -1 on error.
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.
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
This routine is used by the system status demon
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
for the host
The information is updated by the system status demon
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 . 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.
|November 07, 2006|