usr/src/man/man9f/proc_signal.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.,
   3 .\" All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH PROC_SIGNAL 9F "Jan 16, 2006"
   8 .SH NAME
   9 proc_signal, proc_ref, proc_unref \- send a signal to a process
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15 #include <sys/signal.h>
  16
  17
  18
  19 \fBvoid *\fR\fBproc_ref\fR(void)
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBvoid\fR\fBproc_unref\fR(\fBvoid\fR \fI*pref\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBproc_signal\fR(\fBvoid\fR \fI*pref\fR, \fBint\fR \fIsig\fR);
  30 .fi
  31
  32 .SH INTERFACE LEVEL
  33 .sp
  34 .LP
  35 Solaris DDI specific (Solaris DDI).
  36 .SH PARAMETERS
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIpref\fR\fR
  41 .ad
  42 .RS 8n
  43 A handle for the process to be signalled.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIsig\fR\fR
  50 .ad
  51 .RS 8n
  52 Signal number to be sent to the process.
  53 .RE
  54
  55 .SH DESCRIPTION
  56 .sp
  57 .LP
  58 This set of routines allows a driver to send a signal to a process. The routine
  59 \fBproc_ref()\fR is used to retrieve an unambiguous reference to the process
  60 for signalling purposes. The return value can be used as a unique handle on the
  61 process, even if the process dies. Because system resources are committed to a
  62 process reference, \fBproc_unref()\fR should be used to remove it as soon as it
  63 is no longer needed.\fBproc_signal()\fR is used to send signal \fIsig\fR to the
  64 referenced process. The following set of signals may be sent to a process from
  65 a driver:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBSIGHUP\fR\fR
  70 .ad
  71 .RS 12n
  72 The device has been disconnected.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBSIGINT\fR\fR
  79 .ad
  80 .RS 12n
  81 The interrupt character has been received.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBSIGQUIT\fR\fR
  88 .ad
  89 .RS 12n
  90 The quit character has been received.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBSIGPOLL\fR\fR
  97 .ad
  98 .RS 12n
  99 A pollable event has occurred.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBSIGKILL\fR\fR
 106 .ad
 107 .RS 12n
 108 Kill the process (cannot be caught or ignored).
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBSIGWINCH\fR\fR
 115 .ad
 116 .RS 12n
 117 Window size change.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBSIGURG\fR\fR
 124 .ad
 125 .RS 12n
 126 Urgent data are available.
 127 .RE
 128
 129 .sp
 130 .LP
 131 See \fBsignal.h\fR(3HEAD) for more details on the meaning of these signals.
 132 .sp
 133 .LP
 134 If the process has exited at the time the signal was sent, \fBproc_signal()\fR
 135 returns an error code; the caller should remove the reference on the process by
 136 calling \fBproc_unref()\fR.
 137 .sp
 138 .LP
 139 The driver writer must ensure that for each call made to \fBproc_ref()\fR,
 140 there is exactly one corresponding call to \fBproc_unref()\fR.
 141 .SH RETURN VALUES
 142 .sp
 143 .LP
 144 The \fBproc_ref()\fR returns the following:
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fIpref\fR\fR
 149 .ad
 150 .RS 8n
 151 An opaque handle used to refer to the current process.
 152 .RE
 153
 154 .sp
 155 .LP
 156 The \fBproc_signal()\fR returns the following:
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fB0\fR\fR
 161 .ad
 162 .RS 6n
 163 The process existed before the signal was sent.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fB-1\fR\fR
 170 .ad
 171 .RS 6n
 172 The process no longer exists; no signal was sent.
 173 .RE
 174
 175 .SH CONTEXT
 176 .sp
 177 .LP
 178 The \fBproc_unref()\fR and \fBproc_signal()\fR functions can be called from
 179 user, interrupt, or kernel context. The \fBproc_ref()\fR function should be
 180 called only from user context.
 181 .SH SEE ALSO
 182 .sp
 183 .LP
 184 \fBsignal.h\fR(3HEAD), \fBputnextctl1\fR(9F)
 185 .sp
 186 .LP
 187 \fIWriting Device Drivers\fR