[src/trunk]: src/lib/librumpuser document rumpuser_kill()

[pooka <pooka%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a68bd4255b85
branches:  trunk
changeset: 793574:a68bd4255b85
user:      pooka <pooka%NetBSD.org@localhost>
date:      Thu Feb 20 00:43:26 2014 +0000

description:
document rumpuser_kill()

diffstat:

 lib/librumpuser/rumpuser.3 |  49 ++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 2 deletions(-)

diffs (70 lines):

diff -r fefccd9f1c4d -r a68bd4255b85 lib/librumpuser/rumpuser.3
--- a/lib/librumpuser/rumpuser.3        Thu Feb 20 00:42:27 2014 +0000
+++ b/lib/librumpuser/rumpuser.3        Thu Feb 20 00:43:26 2014 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: rumpuser.3,v 1.17 2014/02/14 00:33:51 pooka Exp $
+.\"     $NetBSD: rumpuser.3,v 1.18 2014/02/20 00:43:26 pooka Exp $
 .\"
 .\" Copyright (c) 2013 Antti Kantee.  All rights reserved.
 .\"
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd February 13, 2013
+.Dd February 19, 2014
 .Dt RUMPUSER 3
 .Os
 .Sh NAME
@@ -428,6 +428,51 @@
 .Fn rumpuser_dprintf "const char *fmt" "..."
 .Pp
 Do output based on printf-like parameters.
+.Ss Signals
+.Pp
+A rump kernel should be able to send signals to client programs
+due to some standard interfaces including signal delivery in their
+specifications.
+Examples of these interfaces include
+.Xr setitimer 2
+and
+.Xr write 2 .
+The
+.Fn rumpuser_kill
+function advises the hypercall implementation to raise a signal for the
+process containing the rump kernel.
+.Pp
+.Ft int
+.Fn rumpuser_kill "int64_t pid" "int sig"
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa pid
+The pid of the rump kernel process that the signal is directed to.
+This value may be used as the hypervisor as a hint on how to deliver
+the signal.
+The value
+.Dv RUMPUSER_PID_SELF
+may also be specified to indicate no hint.
+This value will be removed in a future version of the hypercall interface.
+.It Fa sig
+Number of signal to raise.
+The value is in NetBSD signal number namespace.
+In case the host has a native representation for signals, the
+value should be translated before the signal is raised.
+In case there is no mapping between
+.Fa sig
+and native signals (if any), the behavior is implementation-defined.
+.El
+.Pp
+A rump kernel will ignore the return value of this hypercall.
+The only implication of not implementing
+.Fn rumpuser_kill
+is that some application programs may not experience expected behavior
+for standard interfaces.
+.Pp
+As an aside,the
+.Xr rump_sp 7
+protocol provides equivalent functionality for remote clients.
 .Ss Random pool
 .Ft int
 .Fn rumpuser_getrandom "void *buf" "size_t buflen" "int flags" "size_t *retp"