Family: Rights
Authors: Ben Jackson, KSB Braunsdorf
Mail: ksb@npcguild.org
Version: 3.1
Bugs: None known.

Introduction

UNIX operating systems allows passing open file descriptors between processes via a UNIX domain socket pair (aka a pipe, now days). This module provides a portable abstraction to send and receive file descriptors.

Configuration

Provide a standard "machine.h" which defines:

#define HAVE_SCM_RIGHTS: Defined to be the integer 0 if the local UNIX flavor doesn't have the SCM_RIGHTS cmsg_type.
#define HAVE_STRERROR: Defined to be 1 if the local system include files define strerror(3).
#define RIGHTS_TAG_LINE: Optionally the implementor may define a maximum size for the tag-string sent with the access rights. The default is 64 bytes, which is intended to be a used as a token to ensure synchronized exchanges (nothing more).

Synopsis

#include <sys/types.h>
#include <sys/param.h>
#include <sys/socket.h>
#include <sys/uio.h>
#include <errno.h>

#include "machine.h"
#include "fdrights.h"

Description

The modules is used by xclate, wrapw and other tools to pass access rights (open file descriptors) between processes.

Provides

extern int RightsSendFd(int fd, int *list, unsigned count, char *tag);

Send a list of file descriptors to a peer process.

The peer process should be calling RightsRecvFd on the other end of fd, the list pointer points to a vector of count file descriptors. The tag strings is sent in the message.

A tag of (char *)0 sends the message "ok".

extern int RightsRecvFd(int fd, int *list, unsigned count, char *tag, size_t *length);

extern char acRightsRecvBuf[RIGHTS_TAG_LINE];

Waits for a peer process to send count access rights on file descriptor fd.

The new file descriptor indexes are recorded in list, which might be large enough to hold the list sent by the peer. The synchronization string is copied into tag which must be at least length bytes long, the number of bytes returned is the return value of this function call.

When tag is provided as (char *)0 the global buffer acRightsRecvBuf is used.

extern int RightsWrap(int fd, char *pcSuffix, void *pvData, char *pcType);

This function is the wegde that makes wrapw work in advanced wrappers (like ksb's xclate) that work across machines (through sshw). This hook is what divConnect from mkcmd's library needs to "wrap-back" to a wrapw diversion on another host. It must be linked with RightsRecvFd, since it calls that function.

extern int RopenSplit(void (*)());

extern int ropen(char *, int , int );

An example application of this technology. Taken from Steven's book and adapted to use this interface.

EXAMPLE

See the test driver embedded in the module, via:

explode fdrights.h
explode fdrights.c
more fdrightstest.c

Diagnostics

None.

Todo List