Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

RUMPCLIENT(3)              Library Functions Manual              RUMPCLIENT(3)

     rumpclient - rump client library

     library "rumpclient"

     #include <rump/rumpclient.h>
     #include <rump/rump_syscalls.h>




     struct rumpclient_fork *

     rumpclient_fork_init(struct rumpclient_fork *rfp);

     rumpclient_fork_cancel(struct rumpclient_fork *rfp);

     rumpclient_exec(const char *path, char *const argv[],
         char *const envp[]);

     rumpclient_daemon(int nochdir, int noclose);

     rumpclient_setconnretry(time_t retrytime);

     rumpclient_syscall(int num, const void *sysarg, size_t argsize,
         register_t *retval);

     rumpclient 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.

           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).

           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
           kernel file descriptors.

           Like above, but the host uses vfork(2).

           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.

           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.

           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
           program control.  However, since all rump clients call the init
           routine, 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.

           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
           connection the rump kernel context will be that of a newly
           connected client.  This means all previous kernel state such as
           file descriptors 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:

                 Attempt reconnection indefinitely.

                 Attempt reconnect exactly once.  What this precisely means
                 depends on the situation: e.g. getting EHOSTUNREACH
                 immediately or the TCP connection request timeouting are
                 considered to be one retry.

                 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
                 communicate 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.

     rumpclient routines return -1 in case of error and set errno.  In case of
     success a non-negative integer is returned, where applicable.

     rump_server(1), rump(3), rump_sp(7)

     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.

NetBSD 9.99                    February 16, 2011                   NetBSD 9.99