RUMPCLIENT(3) BSD Library Functions Manual RUMPCLIENT(3)NAMErumpclient — rump client library
LIBRARY
library “rumpclient” (librumpclient, -lrumpclient)
SYNOPSIS
#include <rump/rumpclient.h>
#include <rump/rump_syscalls.h>
int
rumpclient_init();
pid_t
rumpclient_fork();
pid_t
rumpclient_vfork();
struct rumpclient_fork *
rumpclient_prefork();
int
rumpclient_fork_init(struct rumpclient_fork *rfp);
void
rumpclient_fork_cancel(struct rumpclient_fork *rfp);
int
rumpclient_exec(const char *path, char *const argv[],
char *const envp[]);
int
rumpclient_daemon(int nochdir, int noclose);
void
rumpclient_setconnretry(time_t retrytime);
int
rumpclient_syscall(int num, const void *sysarg, size_t argsize,
register_t *retval);
DESCRIPTIONrumpclient is the clientside implementation of the rump_sp(7) facility.
It can be used to connect to a rump kernel server and make system call
style requests.
Every connection to a rump kernel server creates a new process context in
the rump kernel. By default a process is inherited from init, but
through existing connections and the forking facility offered by
rumpclient it is possible to form process trees.
rumpclient_init()
Initialize rumpclient. The server address is determined from the
environment variable RUMP_SERVER according to syntax described in
rump_sp(7). The new process is registered to the rump kernel with
the command name from getprogname(3).
rumpclient_fork()
Fork a rump client process. This also causes a host process fork
via fork(2). The child will have a copy of the parent's rump ker‐
nel file descriptors.
rumpclient_vfork()
Like above, but the host uses vfork(2).
rumpclient_prefork()
Low-level routine which instructs the rump kernel that the current
process is planning to fork. The routine returns a non-NULL cookie
if successful.
rumpclient_fork_init(rfp)
Low-level routine which works like rumpclient_init(), with the
exception that it uses the rfp context created by a call to
rumpclient_prefork(). This is typically called from the child of a
fork(2) call.
rumpclient_fork_cancel(rfp)
Cancel previously initiated prefork context. This is useful for
error handling in case a full fork could not be carried through.
rumpclient_exec(path, argv, envp)
This call is a rumpclient wrapper around execve(2). The wrapper
makes sure that the rump kernel process context stays the same in
the newly executed program. This means that the rump kernel PID
remains the same and the same rump file descriptors are available
(apart from ones which were marked with FD_CLOEXEC).
It should be noted that the newly executed program must call
rumpclient_init() before any other rump kernel communication can
take place. The wrapper cannot do it because it no longer has pro‐
gram control. However, since all rump clients call the init rou‐
tine, this should not be a problem.
rumpclient_daemon(noclose, nochdir)
This function performs the equivalent of daemon(3), but also
ensures that the internal call to fork(2) is handled properly.
This routine is provided for convenience.
rumpclient_setconnretry(retrytime)
Set the timeout for how long the client attempts to reconnect to
the server in case of a broken connection. After the timeout
expires the client will return a failure for that particular
request. It is critical to note that after a restablished connec‐
tion the rump kernel context will be that of a newly connected
client. This means all previous kernel state such as file descrip‐
tors will be lost. It is largely up to a particular application if
this has impact or not. For example, web browsers tend to recover
fairly smoothly from a kernel server reconnect, while sshd(8) gets
confused if its sockets go missing.
If retrytime is a positive integer, it means the number of seconds
for which reconnection will be attempted. The value 0 means that
reconnection will not be attempted, and all subsequent operations
will return the errno ENOTCONN.
Additionally, the following special values are accepted:
RUMPCLIENT_RETRYCONN_INFTIME
Attempt reconnection indefinitely.
RUMPCLIENT_RETRYCONN_ONCE
Attempt reconnect exactly once. What this precisely means
depends on the situation: e.g. getting EHOSTUNREACH immedi‐
ately or the TCP connection request timeouting are considered
to be one retry.
RUMPCLIENT_RETRYCONN_DIE
In case of a broken connection is detected at runtime, call
exit(3). This is useful for example in testing. It ensures
that clients are killed immediately when they attempt to com‐
municate with a halted server.
rumpclient_syscall(num, sysarg, argsize, retval)
Execute an "indirect" system call. In the normal case system calls
are executed through the interfaces in <rump/rump_syscalls.h> (for
example rump_sys_read(fd, buf, nbytes)). This interface allows
calling the server with pre-marshalled arguments.
Additionally, all of the supported rump system calls are available
through this library. See <rump/rump_syscalls.h> for a list.
RETURN VALUESrumpclient routines return -1 in case of error and set errno. In case of
success a non-negative integer is returned, where applicable.
SEE ALSOrump_server(1), rump(3), rump_sp(7)CAVEATS
Interfaces for a cryptographically authenticated client-server handshake
do not currently exist. This can be worked around with e.g. host access
control and an ssh tunnel.
BSD February 16, 2011 BSD
