sema_destroy(9f)

1semaphore(9F)            Kernel Functions for Drivers            semaphore(9F)
2
3
4

NAME

6       semaphore,   sema_init,   sema_destroy,   sema_p,  sema_p_sig,  sema_v,
7       sema_tryp - semaphore functions
8

SYNOPSIS

10       #include <sys/ksynch.h>
11
12
13
14       void sema_init(ksema_t *sp, uint_t val, char *name, ksema_type_t type,
15             void *arg);
16
17
18       void sema_destroy(ksema_t *sp);
19
20
21       void sema_p(ksema_t *sp);
22
23
24       void sema_v(ksema_t *sp);
25
26
27       int sema_p_sig(ksema_t *sp);
28
29
30       int sema_tryp(ksema_t *sp);
31
32

INTERFACE LEVEL

34       Solaris DDI specific (Solaris DDI).
35

PARAMETERS

37       sp      A pointer to a semaphore, type ksema_t.
38
39
40       val     Initial value for semaphore.
41
42
43       name    Descriptive string. This is obsolete and should be NULL.  (Non-
44               NULL strings are legal, but they are a waste of kernel memory.)
45
46
47       type    Variant  type  of the semaphore. Currently, only SEMA_DRIVER is
48               supported.
49
50
51       arg     Type-specific argument; should be NULL.
52
53

DESCRIPTION

55       These functions implement counting semaphores as described by Dijkstra.
56       A semaphore has a value which is atomically decremented by sema_p() and
57       atomically incremented by sema_v(). The value must  always  be  greater
58       than or equal to zero. If sema_p() is called and the value is zero, the
59       calling thread is blocked until  another  thread  performs  a  sema_v()
60       operation on the semaphore.
61
62
63       Semaphores  are  initialized by calling sema_init(). The argument, val,
64       gives the initial value for the semaphore.  The  semaphore  storage  is
65       provided by the caller but more may be dynamically allocated, if neces‐
66       sary, by sema_init(). For this reason, sema_destroy() should be  called
67       before deallocating the storage containing the semaphore.
68
69
70       The  sema_p_sig()  function decrements the semaphore, as does sema_p().
71       However, if the semaphore value is zero, sema_p_sig() will return with‐
72       out decrementing the value if a signal (that is, from kill(2)) is pend‐
73       ing for the thread.
74
75
76       The sema_tryp() function will decrement the semaphore value only if  it
77       is greater than zero, and will not block.
78

RETURN VALUES

80       0    sema_tryp() could not decrement the semaphore value because it was
81            zero.
82
83
84       1    sema_p_sig() was not able to decrement  the  semaphore  value  and
85            detected a pending signal.
86
87

CONTEXT

89       These  functions can be called from user, interrupt, or kernel context,
90       except for sema_init() and sema_destroy(), which  can  be  called  from
91       user or kernel context only. None of these functions can be called from
92       a high-level interrupt context. In most cases,  sema_v()  and  sema_p()
93       should not be called from any interrupt context.
94
95
96       If  sema_p()  is used from interrupt context, lower-priority interrupts
97       will not be serviced during the wait. This means  that  if  the  thread
98       that  will  eventually perform the sema_v() becomes blocked on anything
99       that requires the lower-priority interrupt, the system will hang.
100
101
102       For example, the thread that will perform  the  sema_v()  may  need  to
103       first  allocate  memory. This memory allocation may require waiting for
104       paging I/O to complete, which may require a lower-priority disk or net‐
105       work  interrupt  to  be  serviced. In general, situations like this are
106       hard to predict, so it is advisable to avoid waiting on  semaphores  or
107       condition variables in an interrupt context.
108