Kernel Functions for Drivers                        semaphore(9F)



NAME
     semaphore,  semainit,  semadestroy,  semap,   semapsig,
     semav, sematryp - semaphore functions

SYNOPSIS
     #include 



     void semainit(ksemat *sp, uintt val, char *name, ksematypet type,
           void *arg);


     void semadestroy(ksemat *sp);


     void semap(ksemat *sp);


     void semav(ksemat *sp);


     int semapsig(ksemat *sp);


     int sematryp(ksemat *sp);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
     sp      A pointer to a semaphore, type ksemat.


     val     Initial value for semaphore.


     name    Descriptive string. This is obsolete and  should  be
             NUL.  (Non-NUL  strings  are legal, but they are a
             waste of kernel memory.)


     type    Variant  type  of  the  semaphore.  Currently,  only
             SEMADRIVER is supported.


     arg     Type-specific argument; should be NUL.


DESCRIPTION




SunOS 5.11           Last change: 7 May 1997                    1






Kernel Functions for Drivers                        semaphore(9F)



     These functions implement counting semaphores  as  described
     by  Dijkstra.  A  semaphore  has a value which is atomically
     decremented  by  semap()  and  atomically  incremented   by
     semav().  The value must always be greater than or equal to
     zero. If semap() is called and the value is zero, the  cal-
     ling  thread  is  blocked  until  another  thread performs a
     semav() operation on the semaphore.


     Semaphores are initialized by calling semainit(). The argu-
     ment,  val,  gives  the initial value for the semaphore. The
     semaphore storage is provided by the caller but more may  be
     dynamically  allocated,  if  necessary,  by semainit(). For
     this reason, semadestroy() should be called before  deallo-
     cating the storage containing the semaphore.


     The semapsig() function decrements the semaphore, as  does
     semap().   However,   if   the  semaphore  value  is  zero,
     semapsig() will return without decrementing the value if a
     signal (that is, from kill(2)) is pending for the thread.


     The sematryp() function will decrement the semaphore  value
     only if it is greater than zero, and will not block.

RETURN VALUES
     0    sematryp() could not  decrement  the  semaphore  value
          because it was zero.


     1    semapsig() was not able to  decrement  the  semaphore
          value and detected a pending signal.


CONTEXT
     These functions can be called from user, interrupt, or  ker-
     nel  context,  except  for  semainit()  and semadestroy(),
     which can be called from user or kernel context  only.  None
     of these functions can be called from a high-level interrupt
     context. In most cases, semav() and semap() should not  be
     called from any interrupt context.


     If semap() is used from interrupt  context,  lower-priority
     interrupts  will not be serviced during the wait. This means
     that if the thread that will eventually perform the semav()
     becomes blocked on anything that requires the lower-priority
     interrupt, the system will hang.






SunOS 5.11           Last change: 7 May 1997                    2






Kernel Functions for Drivers                        semaphore(9F)



     For example, the thread that will perform the  semav()  may
     need  to  first  allocate memory. This memory allocation may
     require waiting  for  paging  I/O  to  complete,  which  may
     require  a  lower-priority  disk  or network interrupt to be
     serviced. In general,  situations  like  this  are  hard  to
     predict,  so  it is advisable to avoid waiting on semaphores
     or condition variables in an interrupt context.

SEE ALSO
     kill(2), condvar(9F), mutex(9F)


     Writing Device Drivers










































SunOS 5.11           Last change: 7 May 1997                    3