Module Name: src Committed By: pooka Date: Wed Feb 16 23:45:40 UTC 2011
Modified Files: src/lib/librumpclient: Makefile Added Files: src/lib/librumpclient: rumpclient.3 Log Message: add some excuse of a manpage for librumpclient To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/librumpclient/Makefile cvs rdiff -u -r0 -r1.1 src/lib/librumpclient/rumpclient.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/librumpclient/Makefile diff -u src/lib/librumpclient/Makefile:1.2 src/lib/librumpclient/Makefile:1.3 --- src/lib/librumpclient/Makefile:1.2 Tue Nov 23 12:41:47 2010 +++ src/lib/librumpclient/Makefile Wed Feb 16 23:45:40 2011 @@ -1,10 +1,11 @@ -# $NetBSD: Makefile,v 1.2 2010/11/23 12:41:47 pooka Exp $ +# $NetBSD: Makefile,v 1.3 2011/02/16 23:45:40 pooka Exp $ # .PATH: ${.CURDIR}/../../sys/rump/librump/rumpkern LIB= rumpclient USE_SHLIBDIR= yes +MAN= rumpclient.3 .include <bsd.own.mk> Added files: Index: src/lib/librumpclient/rumpclient.3 diff -u /dev/null src/lib/librumpclient/rumpclient.3:1.1 --- /dev/null Wed Feb 16 23:45:40 2011 +++ src/lib/librumpclient/rumpclient.3 Wed Feb 16 23:45:40 2011 @@ -0,0 +1,202 @@ +.\" $NetBSD: rumpclient.3,v 1.1 2011/02/16 23:45:40 pooka Exp $ +.\" +.\" Copyright (c) 2011 Antti Kantee. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 16, 2011 +.Dt RUMPCLIENT 3 +.Os +.Sh NAME +.Nm rumpclient +.Nd rump client library +.Sh LIBRARY +.Lb rumpclient (librumpclient, \-lrumpclient) +.Sh SYNOPSIS +.In rump/rumpclient.h +.In rump/rump_syscalls.h +.Ft int +.Fn rumpclient_init +.Ft pid_t +.Fn rumpclient_fork +.Ft pid_t +.Fn rumpclient_vfork +.Ft struct rumpclient_fork * +.Fn rumpclient_prefork +.Ft int +.Fn rumpclient_fork_init "struct rumpclient_fork *rfp" +.Ft void +.Fn rumpclient_fork_cancel "struct rumpclient_fork *rfp" +.Ft int +.Fn rumpclient_exec "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn rumpclient_daemon "int nochdir" "int noclose" +.Ft void +.Fn rumpclient_setconnretry "time_t retrytime" +.Ft int +.Fo rumpclient_syscall +.Fa "int num" "const void *sysarg" "size_t argsize" "register_t *retval" +.Fc +.Sh DESCRIPTION +.Nm +is the clientside implementation of the +.Xr rump_sp 7 +facility. +It can be used to connect to a rump kernel server and make system call +style requests. +.Pp +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 +.Nm +it is possible to form process trees. +.Bl -tag -width xxxx +.It Fn rumpclient_init +Initialize +.Nm . +The server address is determined from the environment variable +.Dv RUMP_SERVER +according to syntax described in +.Xr rump_sp 7 . +The new process is registered to the rump kernel with the command +name from +.Xr getprogname 3 . +.It Fn rumpclient_fork +Fork a rump client process. +This also causes a host process fork via +.Xr fork 2 . +The child will have a copy of the parent's rump kernel file descriptors. +.It Fn rumpclient_vfork +Like above, but the host uses +.Xr vfork 2 . +.It Fn 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 succesful. +.It Fn rumpclient_fork_init rfp +Low-level routine which works like +.Fn rumpclient_init , +with the exception that it uses the +.Ar rfp +context created by a call to +.Xr rumpclient_prefork . +This is typically called from the child of a +.Xr fork 2 +call. +.It Fn 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. +.It Fn rumpclient_exec path argv envp +This call is a +.Nm +wrapper around +.Xr 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 +.Dv FD_CLOEXEC ) . +.Pp +It should be noted that the newly executed program must call +.Fn 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. +.It Fn rumpclient_daemon noclose nochdir +This function performs the equivalent of +.Xr daemon 3 , +but also ensures that the internal call to +.Xr fork 2 +is handled properly. +This routine is provided for convenience. +.It Fn 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 +.Xr sshd 8 +gets confused if its sockets go missing. +.Pp +If +.Ar 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 +.Dv ENOTCONN . +.Pp +Additionally, the following special values are accepted: +.Bl -tag -width xxxx +.It Dv RUMPCLIENT_RETRYCONN_INFTIME +Attempt reconnection indefinitely. +.It Dv RUMPCLIENT_RETRYCONN_ONCE +Attempt reconnect exactly once. +What this precisely means depends on the situation: e.g. getting +.Dv EHOSTUNREACH +immediately or the TCP connection request timeouting are considered +to be one retry. +.It Dv RUMPCLIENT_RETRYCONN_DIE +In case of a broken connection is detected at runtime, call +.Xr 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. +.El +.It Fn rumpclient_syscall num sysarg argsize retval +Execute an "indirect" system call. +In the normal case system calls are executed through the interfaces in +.In rump/rump_syscalls.h +(for example +.Fn rump_sys_read fd buf nbytes ) . +This interface allows calling the server with pre-marshalled arguments. +.El +.Pp +Additionally, all of the supported rump system calls are available +through this library. +See +.In rump/rump_syscalls.h +for a list. +.Sh RETURN VALUES +.Nm +routines return \-1 in case of error and set errno. +In case of success a non-negative integer is returned, where applicable. +.Sh SEE ALSO +.Xr rump_server 1 , +.Xr rump 3 , +.Xr rump_sp 7 +.Sh 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.