rump_lwproc(3) [netbsd man page]

RUMP_LWPROC(3)						   BSD Library Functions Manual 					    RUMP_LWPROC(3)

NAME

     rump_lwproc -- rump process/lwp management

LIBRARY

     rump kernel (librump, -lrump)

SYNOPSIS

     #include <rump/rump.h>

     int
     rump_pub_lwproc_rfork(int flags);

     int
     rump_pub_lwproc_newlwp(pid_t pid);

     void
     rump_pub_lwproc_switch(struct lwp *l);

     void
     rump_pub_lwproc_releaselwp();

     struct lwp *
     rump_pub_lwproc_curlwp();

DESCRIPTION

     In a normal operating system model a process is a resource container and a thread (lwp) is the execution context.	Every lwp is associated
     with exactly one process, and a process is associated with one or more lwps.  The current lwp (curlwp) indicates the current process and
     determines which resources, such as UID/GID, current working directory, and file descriptor table, are currently used.  These basic princi-
     ples apply to rump kernels as well, but since rump uses the host's thread and process context directly, the rules for how thread context is
     determined are different.

     In the rump model, each host thread (pthread) is either bound to a rump kernel lwp or accesses the rump kernel with an implicit thread con-
     text associated with pid 1.  An implicit thread context is created every time the rump kernel is entered and disbanded upon exit.	While con-
     venient for occasional calls, creating an implicit thread uses a shared resource which can become highly contended in a multithreaded situa-
     tion.  It is therefore recommended that dedicated threads are created.

     The association between host threads and the rump kernel curlwp is left to the caller.  It is possible to create a dedicated host thread for
     every rump kernel lwp or multiplex them on top of a single host thread.  After rump lwps have been created, switching curlwp is very cheap --
     faster than a thread context switch on the host.  In case multiple lwps/processes are created, it is the caller's responsibility to keep
     track of them and release them when they are no longer necessary.	Like other rump kernel resources, procs/lwps will be released when the
     process hosting the rump kernel exits.

     rump_pub_lwproc_rfork()
	   Create a process, one lwp inside it and set curlwp to the new lwp.  The flags parameter controls how file descriptors are inherited
	   from the parent.  By default (flags=0) file descriptors are shared.	Other options are:

	   RUMP_RFFDG	  Copy file descriptors from parent.  This is what fork(2) does.

	   RUMP_RFCFDG	  File descriptors neither copied nor shared, i.e. new process does not have access to the parent's file descriptors.

	   This routine returns 0 for success or an errno indicating the reason for failure.  The new process id can be retrieved in the normal
	   fashion by calling rump_sys_getpid().

     rump_pub_lwproc_newlwp(pid)
	   Create a new lwp attached to the process specified by pid.  Sets curlwp to the new lwp.  This routine returns 0 for success or an errno
	   indicating the reason for failure.

     rump_pub_lwproc_switch(l)
	   Sets curlwp to l.  In case the new thread is associated with a different process than the current one, the process context is also
	   switched.  The special value NULL sets curlwp to implicit context.  Switching to an already running lwp, i.e. attempting to use the
	   same curlwp in two host threads simultaneously causes a fatal error.

     rump_pub_lwproc_releaselwp()
	   Release curlwp and set curlwp to context.  In case curlwp was the last thread inside the current process, the process container is also
	   released.  Calling this routine without a dedicated curlwp is a fatal error.

     rump_pub_lwproc_curlwp()
	   Returns curlwp or NULL if the current context is an implicit context.

SEE ALSO

     getpid(2), rump(3)

HISTORY

     rump_lwproc first appeared in NetBSD 6.0.

BSD
								  January 2, 2011							       BSD

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 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 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 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 rou-
	   tine 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 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:

	   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 immediately 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 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-negative 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