Re: lookupd-style daemon

[Matthew Dillon <dillon@xxxxxxxxxxxxxxxxxxxx>]

    Yah, libcaps is indeed stable, though not enabled by default.  A
    sysctl kern.caps_enabled=1 will enable it.  The only issue with it
    is probably one with unbounded internal kernel memory allocation.

    libcaps is designed to create a messaging abstraction within a machine.
    The way you access a remote service is by building a local CAPS service 
    that then communicates with the remote machine(s).

    I have copied the code documentation below and added to it.  No manual
    pages have been written for it. 

    I would really appreciate it if someone could create manual pages
    for these functions!


    int caps_sys_service(const char *name, uid_t uid, gid_t gid,
			 int upcid, int flags)

	Create an IPC service using the specified name, uid, gid, and flags.
	Either uid or gid can be -1, but not both.  The port identifier is
	returned.

	upcid can either be an upcall or a kqueue identifier (XXX)  UPCID
	is not currently implemented.

	If an error is occurs, -1 is returned and errno is set to:

	EOPNOTSUPP 	The CAPS system has not been enabled with
			kern.caps_enabled

	EINVAL		An invalid argument was specified.


    int caps_sys_client(const char *name, uid_t uid, gid_t gid, 
			int upcid, int flags);

	Create an IPC client connected to the specified service.  Either
	uid or gid may be -1, indicating a wildcard, but not both.  The
	port identifier is returned.  Programs connecting to a 'generic'
	service typically first try (getuid(), -1), then try (getgid(), -1),
	then try (0, 0).

	upcid can either be an upcall or a kqueue identifier (XXX)  UPCID
	is not currently implemented.

	If an error is occurs, -1 is returned and errno is set to:

	EOPNOTSUPP 	The CAPS system has not been enabled with
			kern.caps_enabled

	EINVAL		An invalid argument was specified.

    int caps_sys_close(int portid)

	Terminate an IPC link previously created with caps_sys_service() or
	caps_sys_client().  Any unreplied messages will be automatically
	replied by the kernel.

	If an error is occurs, -1 is returned and errno is set to:

	EINVAL		The portid could not be found.


    int caps_sys_setgen(int portid, off_t gen)

	Set the 64 bit generation number for a CAPS link.  A service
	typically changes the generation number to indicate that it has
	been restarted.

	If an error is occurs, -1 is returned and errno is set to:

	EINVAL		The portid could not be found.

	ENOTCONN	If the process originally creating the port forked,
			this error will be returned when the child process
			attempts to access the port.  The child process is
			expected to create its own port.


    off_t caps_sys_getgen(int portid)

	Get the 64 bit generation number for a CAPS link.  The generation
	number is typically used to allow a client to detect when a service
	has been restarted.

	If an error is occurs, -1 is returned and errno is set to:

	EINVAL		The portid could not be found.

	ENOTCONN	If the process originally creating the port forked,
			this error will be returned when the child process
			attempts to access the port.  The child process is
			expected to create its own port.

    off_t caps_sys_put(int portid, const void *msg, int msgsize)

	Send an opaque message of the specified size to the specified
	port.  This function is only used on the client-side.  

	The memory associated with the message must be left intact until
	the message is returned.  The kernel does not make a copy of the
	message.  The message may not exceed 128KB.

	A 64 bit message identifier is returned.

	If an error is occurs, -1 is returned and errno is set to:

	EINVAL		An invalid argument was specified.

	ENOTCONN	If the process originally creating the port forked,
			this error will be returned when the child process
			attempts to access the port.  The child process is
			expected to create its own port.

			This error is also returned if the remote end
			closed its connection and is no longer available.

	ENOBUFS		The maximum number of in-transmit messages has
			been reached.  No more messages can be sent
			until some of them are replied.


    int caps_sys_reply(int portid, const void *msg, int msgsize, off_t msgid)

	Reply to the received CAPS message identified by msgid.  The reply
	may contain opaque data.  This function is only used on the
	server-side.

	The server may reply a message without retrieving its data.

	The memory associated with the message must be left intact until
	an acknowledgement is returned at a later time (see caps_sys_get()).
	The kernel does not make a copy of the message.  The message may
	not exceed 128KB.

	If an error is occurs, -1 is returned and errno is set to:

	EINVAL		An invalid argument was specified.

	ENOTCONN	If the process originally creating the port forked,
			this error will be returned when the child process
			attempts to access the port.  The child process is
			expected to create its own port.

			This error is also returned if the remote end
			closed its connection and is no longer available.

			NOTE: a child process may not reply to a message
			received by its parent.


    int caps_sys_get(int portid, void *msg, int maxsize, 
		     struct caps_msgid *msgid, struct caps_cred *ccr)
    int caps_sys_wait(int portid, void *msg, int maxsize,
		     struct caps_msgid *msgid, struct caps_cred *ccr)

	Retrieve the next ready message on the port, store its message id
	and other information in *msgid and its creds in *ccr.  ccr may
	be NULL.  The message is only stored in the msg buffer if it
	fits.
	
	If the message is too large to fit the message id, length, and
	creds are still returned, but the message is not dequeued.  The
	caller is expected to call again with a larger buffer or to 
	call caps_sys_reply() on the message id without retrieving it
	if it does not want to handle the message.

	The returned message can either by a new message from a client,
	a reply from the service, or (on the sevice side only) an
	acknowledgement that a reply we made has been processed by the 
	client.  This state information is stored in msgid->c_state and
	may be:

	CAPMS_REQUEST		Service side received a new request
	CAPMS_REQUEST_RETRY	Reserved for future use
	CAPMS_REPLY		Client side received a reply
	CAPMS_REPLY_RETRY	Reserved for future use
	CAPMS_DISPOSE		Service side's reply has been disposed
				of by the client.

	If you are a CAPS client the only message type you will get is
	CAPMS_REPLY.  If you are a CAPS server you can get CAPS_REQUEST
	or CAPS_DISPOSE.


	This function does not block.

	EINVAL		An invalid argument was specified.

	ENOTCONN	If the process originally creating the port forked,
			this error will be returned when the child process
			attempts to access the port.  The child process is
			expected to create its own port.

			This error is also returned if the remote end
			closed its connection and is no longer available.

	EWOULDBLOCK	No messages are ready.  This applies only to
			caps_sys_get().

	EINTR		The system call was interrupted.  This applies only
			to caps_sys_wait().


    int caps_sys_abort(int portid, off_t msgid, int flags)

	Abort a previously sent message.  You must still wait for the
	message to be returned after sending the abort request.  This
	function will return the appropriate CAPS_ABORT_* code depending
	on whether the abort succeeded or not.

	This function is currently not implemented and CAPS_ABORT_NOTIMPL
	is returned.


					-Matt