[BACK]Return to rumpclient.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / librumpclient

Annotation of src/lib/librumpclient/rumpclient.3, Revision 1.3

1.3     ! wiz         1: .\"     $NetBSD: rumpclient.3,v 1.2 2011/02/17 17:03:17 wiz Exp $
1.1       pooka       2: .\"
                      3: .\" Copyright (c) 2011 Antti Kantee.  All rights reserved.
                      4: .\"
                      5: .\" Redistribution and use in source and binary forms, with or without
                      6: .\" modification, are permitted provided that the following conditions
                      7: .\" are met:
                      8: .\" 1. Redistributions of source code must retain the above copyright
                      9: .\"    notice, this list of conditions and the following disclaimer.
                     10: .\" 2. Redistributions in binary form must reproduce the above copyright
                     11: .\"    notice, this list of conditions and the following disclaimer in the
                     12: .\"    documentation and/or other materials provided with the distribution.
                     13: .\"
                     14: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
                     15: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     16: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     17: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
                     18: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     19: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     20: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     21: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     22: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     23: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     24: .\" SUCH DAMAGE.
                     25: .\"
                     26: .Dd February 16, 2011
                     27: .Dt RUMPCLIENT 3
                     28: .Os
                     29: .Sh NAME
                     30: .Nm rumpclient
                     31: .Nd rump client library
                     32: .Sh LIBRARY
1.3     ! wiz        33: .Lb rumpclient
1.1       pooka      34: .Sh SYNOPSIS
                     35: .In rump/rumpclient.h
                     36: .In rump/rump_syscalls.h
                     37: .Ft int
                     38: .Fn rumpclient_init
                     39: .Ft pid_t
                     40: .Fn rumpclient_fork
                     41: .Ft pid_t
                     42: .Fn rumpclient_vfork
                     43: .Ft struct rumpclient_fork *
                     44: .Fn rumpclient_prefork
                     45: .Ft int
                     46: .Fn rumpclient_fork_init "struct rumpclient_fork *rfp"
                     47: .Ft void
                     48: .Fn rumpclient_fork_cancel "struct rumpclient_fork *rfp"
                     49: .Ft int
                     50: .Fn rumpclient_exec "const char *path" "char *const argv[]" "char *const envp[]"
                     51: .Ft int
                     52: .Fn rumpclient_daemon "int nochdir" "int noclose"
                     53: .Ft void
                     54: .Fn rumpclient_setconnretry "time_t retrytime"
                     55: .Ft int
                     56: .Fo rumpclient_syscall
                     57: .Fa "int num" "const void *sysarg" "size_t argsize" "register_t *retval"
                     58: .Fc
                     59: .Sh DESCRIPTION
                     60: .Nm
                     61: is the clientside implementation of the
                     62: .Xr rump_sp 7
                     63: facility.
                     64: It can be used to connect to a rump kernel server and make system call
                     65: style requests.
                     66: .Pp
                     67: Every connection to a rump kernel server creates a new process
                     68: context in the rump kernel.
                     69: By default a process is inherited from init, but through existing
                     70: connections and the forking facility offered by
                     71: .Nm
                     72: it is possible to form process trees.
                     73: .Bl -tag -width xxxx
                     74: .It Fn rumpclient_init
                     75: Initialize
                     76: .Nm .
                     77: The server address is determined from the environment variable
1.2       wiz        78: .Ev RUMP_SERVER
1.1       pooka      79: according to syntax described in
                     80: .Xr rump_sp 7 .
                     81: The new process is registered to the rump kernel with the command
                     82: name from
                     83: .Xr getprogname 3 .
                     84: .It Fn rumpclient_fork
                     85: Fork a rump client process.
                     86: This also causes a host process fork via
                     87: .Xr fork 2 .
                     88: The child will have a copy of the parent's rump kernel file descriptors.
                     89: .It Fn rumpclient_vfork
                     90: Like above, but the host uses
                     91: .Xr vfork 2 .
                     92: .It Fn rumpclient_prefork
                     93: Low-level routine which instructs the rump kernel that the current
                     94: process is planning to fork.
1.2       wiz        95: The routine returns a
                     96: .Pf non- Dv NULL
                     97: cookie if successful.
1.1       pooka      98: .It Fn rumpclient_fork_init rfp
                     99: Low-level routine which works like
                    100: .Fn rumpclient_init ,
                    101: with the exception that it uses the
                    102: .Ar rfp
                    103: context created by a call to
1.2       wiz       104: .Fn rumpclient_prefork .
1.1       pooka     105: This is typically called from the child of a
                    106: .Xr fork 2
                    107: call.
                    108: .It Fn rumpclient_fork_cancel rfp
                    109: Cancel previously initiated prefork context.
                    110: This is useful for error handling in case a full fork could not
                    111: be carried through.
                    112: .It Fn rumpclient_exec path argv envp
                    113: This call is a
                    114: .Nm
                    115: wrapper around
                    116: .Xr execve 2 .
                    117: The wrapper makes sure that the rump kernel process context stays
                    118: the same in the newly executed program.
                    119: This means that the rump kernel PID remains the same and the same
                    120: rump file descriptors are available (apart from ones which
                    121: were marked with
                    122: .Dv FD_CLOEXEC ) .
                    123: .Pp
                    124: It should be noted that the newly executed program must call
                    125: .Fn rumpclient_init
                    126: before any other rump kernel communication can take place.
                    127: The wrapper cannot do it because it no longer has program control.
                    128: However, since all rump clients call the init routine,
                    129: this should not be a problem.
                    130: .It Fn rumpclient_daemon noclose nochdir
                    131: This function performs the equivalent of
                    132: .Xr daemon 3 ,
                    133: but also ensures that the internal call to
                    134: .Xr fork 2
                    135: is handled properly.
                    136: This routine is provided for convenience.
                    137: .It Fn rumpclient_setconnretry retrytime
                    138: Set the timeout for how long the client attempts to reconnect to
                    139: the server in case of a broken connection.
                    140: After the timeout expires the client will return a failure
                    141: for that particular request.
                    142: It is critical to note that after a restablished connection the
                    143: rump kernel context will be that of a newly connected client.
                    144: This means all previous kernel state such as file descriptors
                    145: will be lost.
                    146: It is largely up to a particular application if this has impact
                    147: or not.
                    148: For example, web browsers tend to recover fairly smoothly from a
                    149: kernel server reconnect, while
                    150: .Xr sshd 8
                    151: gets confused if its sockets go missing.
                    152: .Pp
                    153: If
                    154: .Ar retrytime
                    155: is a positive integer, it means the number of seconds for which
                    156: reconnection will be attempted.
                    157: The value 0 means that reconnection will not be attempted, and all
                    158: subsequent operations will return the errno
1.2       wiz       159: .Er ENOTCONN .
1.1       pooka     160: .Pp
                    161: Additionally, the following special values are accepted:
                    162: .Bl -tag -width xxxx
                    163: .It Dv RUMPCLIENT_RETRYCONN_INFTIME
                    164: Attempt reconnection indefinitely.
                    165: .It Dv RUMPCLIENT_RETRYCONN_ONCE
                    166: Attempt reconnect exactly once.
                    167: What this precisely means depends on the situation: e.g. getting
1.2       wiz       168: .Er EHOSTUNREACH
1.1       pooka     169: immediately or the TCP connection request timeouting are considered
                    170: to be one retry.
                    171: .It Dv RUMPCLIENT_RETRYCONN_DIE
                    172: In case of a broken connection is detected at runtime, call
                    173: .Xr exit 3 .
                    174: This is useful for example in testing.
                    175: It ensures that clients are killed immediately when they attempt
                    176: to communicate with a halted server.
                    177: .El
                    178: .It Fn rumpclient_syscall num sysarg argsize retval
                    179: Execute an "indirect" system call.
                    180: In the normal case system calls are executed through the interfaces in
                    181: .In rump/rump_syscalls.h
                    182: (for example
                    183: .Fn rump_sys_read fd buf nbytes ) .
                    184: This interface allows calling the server with pre-marshalled arguments.
                    185: .El
                    186: .Pp
                    187: Additionally, all of the supported rump system calls are available
                    188: through this library.
                    189: See
                    190: .In rump/rump_syscalls.h
                    191: for a list.
                    192: .Sh RETURN VALUES
                    193: .Nm
                    194: routines return \-1 in case of error and set errno.
                    195: In case of success a non-negative integer is returned, where applicable.
                    196: .Sh SEE ALSO
                    197: .Xr rump_server 1 ,
                    198: .Xr rump 3 ,
                    199: .Xr rump_sp 7
                    200: .Sh CAVEATS
                    201: Interfaces for a cryptographically authenticated client-server
                    202: handshake do not currently exist.
                    203: This can be worked around with e.g. host access control and an ssh
                    204: tunnel.

CVSweb <webmaster@jp.NetBSD.org>