share/man/man9f/semaphore.9f

   1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH SEMAPHORE 9F "May 7, 1997"
   7 .SH NAME
   8 semaphore, sema_init, sema_destroy, sema_p, sema_p_sig, sema_v, sema_tryp \-
   9 semaphore functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ksynch.h>
  14
  15
  16
  17 \fBvoid\fR \fBsema_init\fR(\fBksema_t *\fR\fIsp\fR, \fBuint_t\fR \fIval\fR, \fBchar *\fR\fIname\fR, \fBksema_type_t\fR \fItype\fR,
  18       \fBvoid *\fR\fIarg\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBsema_destroy\fR(\fBksema_t *\fR\fIsp\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBsema_p\fR(\fBksema_t *\fR\fIsp\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBvoid\fR \fBsema_v\fR(\fBksema_t *\fR\fIsp\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBsema_p_sig\fR(\fBksema_t *\fR\fIsp\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBsema_tryp\fR(\fBksema_t *\fR\fIsp\fR);
  44 .fi
  45
  46 .SH INTERFACE LEVEL
  47 .sp
  48 .LP
  49 Solaris \fBDDI\fR specific (Solaris \fBDDI\fR).
  50 .SH PARAMETERS
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIsp\fR\fR
  55 .ad
  56 .RS 8n
  57 A pointer to a semaphore, type \fBksema_t\fR.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIval\fR\fR
  64 .ad
  65 .RS 8n
  66 Initial value for semaphore.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIname\fR\fR
  73 .ad
  74 .RS 8n
  75 Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR
  76 strings are legal, but they are a waste of kernel memory.)
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fItype\fR\fR
  83 .ad
  84 .RS 8n
  85 Variant type of the semaphore. Currently, only \fBSEMA_DRIVER\fR is supported.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIarg\fR\fR
  92 .ad
  93 .RS 8n
  94 Type-specific argument; should be \fINULL\fR.
  95 .RE
  96
  97 .SH DESCRIPTION
  98 .sp
  99 .LP
 100 These functions implement counting semaphores as described by Dijkstra. A
 101 semaphore has a value which is atomically decremented by \fBsema_p()\fR and
 102 atomically incremented by \fBsema_v()\fR. The value must always be greater than
 103 or equal to zero. If \fBsema_p()\fR is called and the value is zero, the
 104 calling thread is blocked until another thread performs a \fBsema_v()\fR
 105 operation on the semaphore.
 106 .sp
 107 .LP
 108 Semaphores are initialized by calling \fBsema_init()\fR. The argument,
 109 \fBval\fR, gives the initial value for the semaphore. The semaphore storage is
 110 provided by the caller but more may be dynamically allocated, if necessary, by
 111 \fBsema_init()\fR. For this reason, \fBsema_destroy()\fR should be called
 112 before deallocating the storage containing the semaphore.
 113 .sp
 114 .LP
 115 The \fBsema_p_sig()\fR function decrements the semaphore, as does
 116 \fBsema_p()\fR. However, if the semaphore value is zero, \fBsema_p_sig()\fR
 117 will return without decrementing the value if a signal (that is, from
 118 \fBkill\fR(2)) is pending for the thread.
 119 .sp
 120 .LP
 121 The \fBsema_tryp()\fR function will decrement the semaphore value only if it is
 122 greater than zero, and will not block.
 123 .SH RETURN VALUES
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB0\fR\fR
 128 .ad
 129 .RS 5n
 130 \fBsema_tryp()\fR could not decrement the semaphore value because it was zero.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fB1\fR\fR
 137 .ad
 138 .RS 5n
 139 \fBsema_p_sig()\fR was not able to decrement the semaphore value and detected a
 140 pending signal.
 141 .RE
 142
 143 .SH CONTEXT
 144 .sp
 145 .LP
 146 These functions can be called from user, interrupt, or kernel context, except
 147 for \fBsema_init()\fR and \fBsema_destroy()\fR, which can be called from user
 148 or kernel context only. None of these functions can be called from a high-level
 149 interrupt context. In most cases, \fBsema_v()\fR and \fBsema_p()\fR should not
 150 be called from any interrupt context.
 151 .sp
 152 .LP
 153 If \fBsema_p()\fR is used from interrupt context, lower-priority interrupts
 154 will not be serviced during the wait. This means that if the thread that will
 155 eventually perform the \fBsema_v()\fR becomes blocked on anything that requires
 156 the lower-priority interrupt, the system will hang.
 157 .sp
 158 .LP
 159 For example, the thread that will perform the \fBsema_v()\fR may need to first
 160 allocate memory. This memory allocation may require waiting for paging
 161 \fBI/O\fR to complete, which may require a lower-priority disk or network
 162 interrupt to be serviced. In general, situations like this are hard to predict,
 163 so it is advisable to avoid waiting on semaphores or condition variables in an
 164 interrupt context.
 165 .SH SEE ALSO
 166 .sp
 167 .LP
 168 \fBkill\fR(2), \fBcondvar\fR(9F), \fBmutex\fR(9F)
 169 .sp
 170 .LP
 171 \fIWriting Device Drivers\fR