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>