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

   1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved
  19 .\" Copyright 2018 Nexenta Systems, Inc.
  20 .\"
  21 .Dd July 30, 2018
  22 .Dt SEMAPHORE 9F
  23 .Os
  24 .Sh NAME
  25 .Nm semaphore ,
  26 .Nm sema_init ,
  27 .Nm sema_destroy ,
  28 .Nm sema_p ,
  29 .Nm sema_p_sig ,
  30 .Nm sema_v ,
  31 .Nm sema_tryp
  32 .Nd semaphore functions
  33 .Sh SYNOPSIS
  34 .In sys/ksynch.h
  35 .Ft void
  36 .Fo sema_init
  37 .Fa "ksema_t *sp"
  38 .Fa "uint_t val"
  39 .Fa "char *name"
  40 .Fa "ksema_type_t type"
  41 .Fa "void *arg"
  42 .Fc
  43 .Ft void
  44 .Fo sema_destroy
  45 .Fa "ksema_t *sp"
  46 .Fc
  47 .Ft void
  48 .Fo sema_p
  49 .Fa "ksema_t *sp"
  50 .Fc
  51 .Ft void
  52 .Fo sema_v
  53 .Fa "ksema_t *sp"
  54 .Fc
  55 .Ft int
  56 .Fo sema_p_sig
  57 .Fa "ksema_t *sp"
  58 .Fc
  59 .Ft int
  60 .Fo sema_tryp
  61 .Fa "ksema_t *sp"
  62 .Fc
  63 .Sh INTERFACE LEVEL
  64 illumos DDI specific (illumos DDI).
  65 .Sh PARAMETERS
  66 .Bl -tag -width Ds
  67 .It Fa sp
  68 A pointer to a semaphore, type
  69 .Vt ksema_t .
  70 .It Fa val











  71 Initial value for semaphore.
  72 .It Fa name
  73 Descriptive string.
  74 This is obsolete and should be
  75 .Dv NULL .
  76 .Po Non- Ns
  77 .Dv NULL
  78 strings are legal, but they are a waste of kernel memory.
  79 .Pc
  80 .It Fa type
  81 Variant type of the semaphore.
  82 Currently, only
  83 .Dv SEMA_DRIVER
  84 is supported.
  85 .It Fa arg
  86 Type-specific argument; should be
  87 .Dv NULL .
  88 .El
  89 .Sh DESCRIPTION
  90 These functions implement counting semaphores as described by Dijkstra.
  91 A semaphore has a value which is atomically decremented by
  92 .Fn sema_p
  93 and atomically incremented by
  94 .Fn sema_v .
  95 The value must always be greater than or equal to zero.
  96 If
  97 .Fn sema_p
  98 is called and the value is zero, the calling thread is blocked until another
  99 thread performs a
 100 .Fn sema_v









 101 operation on the semaphore.
 102 .Pp
 103 Semaphores are initialized by calling
 104 .Fn sema_init .
 105 The argument,
 106 .Fa val ,
 107 gives the initial value for the semaphore.
 108 The semaphore storage is provided by the caller but more may be dynamically
 109 allocated, if necessary, by
 110 .Fn sema_init .
 111 For this reason,
 112 .Fn sema_destroy
 113 should be called before deallocating the storage containing the semaphore.
 114 .Pp
 115 The
 116 .Fn sema_p_sig
 117 function decrements the semaphore, as does
 118 .Fn sema_p .
 119 However, if the semaphore value is zero,
 120 .Fn sema_p_sig
 121 will return without decrementing the value if a signal
 122 .Po that is, from
 123 .Xr kill 2
 124 .Pc
 125 is pending for the thread.
 126 .Pp
 127 The
 128 .Fn sema_tryp
 129 function will decrement the semaphore value only if it is greater than zero, and
 130 will not block.
 131 .Sh CONTEXT










 132 These functions can be called from user, interrupt, or kernel context, except
 133 for
 134 .Fn sema_init
 135 and
 136 .Fn sema_destroy ,
 137 which can be called from user or kernel context only.
 138 None of these functions can be called from a high-level interrupt context.
 139 In most cases,
 140 .Fn sema_v
 141 and
 142 .Fn sema_p
 143 should not be called from any interrupt context.
 144 .Pp
 145 If
 146 .Fn sema_p
 147 is used from interrupt context, lower-priority interrupts will not be serviced
 148 during the wait.
 149 This means that if the thread that will eventually perform the
 150 .Fn sema_v
 151 becomes blocked on anything that requires the lower-priority interrupt, the
 152 system will hang.
 153 .Pp
 154 For example, the thread that will perform the
 155 .Fn sema_v
 156 may need to first allocate memory.
 157 This memory allocation may require waiting for paging I/O to complete, which may
 158 require a lower-priority disk or network interrupt to be serviced.
 159 In general, situations like this are hard to predict, so it is advisable to
 160 avoid waiting on semaphores or condition variables in an interrupt context.
 161 .Pp
 162 Similar to many other synchronization mechanisms, semaphores should not be used
 163 in any code path that requires synchronization while handling system panic, at
 164 which time many of the semaphore operations become no-ops.
 165 .Sh RETURN VALUES
 166 .Bl -tag -width Ds
 167 .It Li 0
 168 .Fn sema_tryp
 169 could not decrement the semaphore value because it was zero.
 170 .It Li 1
 171 .Fn sema_p_sig
 172 was not able to decrement the semaphore value and detected a pending signal.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr kill 2 ,
 176 .Xr condvar 9F ,
 177 .Xr mutex 9F
 178 .Pp
 179 .Em Writing Device Drivers