Unix/Linux Go Back    


NetBSD 6.1.5 - man page for rumpclient (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


RUMPCLIENT(3)			   BSD Library Functions Manual 		    RUMPCLIENT(3)

NAME
     rumpclient -- 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);

DESCRIPTION
     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 fork-
     ing 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 regis-
	   tered 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 kernel 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 program 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 connection
	   the rump kernel context will be that of a newly connected client.  This means all pre-
	   vious kernel state such as file descriptors will be lost.  It is largely up to a par-
	   ticular 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 reconnec-
	   tion 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 situa-
		 tion: e.g. getting EHOSTUNREACH immediately or the TCP connection request time-
		 outing 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 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.

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

SEE ALSO
     rump_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
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:46 PM.