Standard C Library Functions                         semwait(3C)



NAME
     semwait, semtrywait - acquire or wait for a semaphore

SYNOPSIS
     #include 

     int semwait(semt *sem);


     int semtrywait(semt *sem);


DESCRIPTION
     The semwait() function locks the  semaphore  referenced  by
     sem  by  performing a semaphore lock operation on that sema-
     phore. If the semaphore value is currently  zero,  then  the
     calling  thread  will not return from the call to semwait()
     until it either locks the semaphore or the  call  is  inter-
     rupted  by  a  signal.  The semtrywait() function locks the
     semaphore  referenced  by  sem  only  if  the  semaphore  is
     currently  not  locked;  that  is, if the semaphore value is
     currently positive. Otherwise, it does not  lock  the  sema-
     phore.


     Upon successful return, the state of the semaphore is locked
     and  remains  locked until the sempost(3C) function is exe-
     cuted and returns successfully.


     The semwait() function is interruptible by the delivery  of
     a signal.

RETURN VALUES
     The semwait() and semtrywait() functions return  0 if  the
     calling  process  successfully  performed the semaphore lock
     operation on the semaphore designated by sem.  If  the  call
     was  unsuccessful,  the state of the semaphore is unchanged,
     and the function returns -1 and sets errno to  indicate  the
     error.

ERORS
     The  semwait() and semtrywait() functions will fail if:

     EINVAL     The sem function does not refer to a valid  sema-
                phore.


     ENOSYS     The semwait() and  semtrywait()  functions  are
                not supported by the system.





SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                         semwait(3C)



     The  semtrywait() function will fail if:

     EAGAIN     The semaphore was already locked, so it cannot be
                immediately  locked  by  the semtrywait() opera-
                tion.



     The  semwait() and semtrywait() functions may fail if:

     EDEADLK     A deadlock condition was detected; that is,  two
                 separate  processes are waiting for an available
                 resource to be released via a  semaphore  "held"
                 by the other process.


     EINTR       A signal interrupted this function.


USAGE
     Realtime applications may encounter priority inversion  when
     using  semaphores.  The  problem occurs when a high priority
     thread "locks" (that is, waits on) a semaphore that is about
     to be "unlocked" (that is, posted) by a low priority thread,
     but the low priority thread is preempted by a medium  prior-
     ity  thread.  This  scenario  leads to priority inversion; a
     high priority thread is blocked by  lower  priority  threads
     for an unlimited period of time. During system design, real-
     time programmers must take into account the  possibility  of
     this  kind of priority inversion. They can deal with it in a
     number of ways, such as by having critical sections that are
     guarded  by semaphores execute at a high priority, so that a
     thread cannot be preempted while executing in  its  critical
     section.

EXAMPLES
     Example 1 The customer waiting-line in a bank may be  analo-
     gous  to the synchronization scheme of a semaphore utilizing
     semwait() and semtrywait():

       #include 
       #define TELERS 10
       semt  bankline;      /* semaphore */
       int bankinghours(), depositwithdrawal;
       void *customer(), dobusiness(), skipbankingtoday();
       threadt tid;
       ...

       seminit(&bankline,TRUE,TELERS);  /* 10 tellers
                                              available */
       while(bankinghours())
               thrcreate(NUL, NUL, customer,



SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                         semwait(3C)



                   (void *)depositwithdrawal, THREADNEWLWP, &tid);
       ...

       void *
       customer(depositwithdrawal)
       void *depositwithdrawal;
       {
           int thiscustomer, inahurry = 50;
           thiscustomer = rand() % 100;
           if (thiscustomer == inahurry)  {
               if (semtrywait(&bankline) != 0)
               if (errno == EAGAIN) {    /* no teller available */
                   skipbankingtoday(thiscustomer);
                   return;
               }     /*else go immediately to available teller
                      & decrement bankline*/
           }
           else
               semwait(&bankline); /* wait for next teller,
                    then proceed, and decrement bankline */
           dobusiness((int *)depositwithdrawal);
           semgetvalue(&bankline,&numtellers);
           sempost(&bankline); /* increment bankline;
               thiscustomer's teller is now available */
       }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    
     MT-Level                     MT-Safe                     
    
     Standard                     See standards(5).           
    


SEE ALSO
     sempost(3C), attributes(5), standards(5)









SunOS 5.11           Last change: 5 Feb 2008                    3