Manual Pages for UNIX Operating System command usage for man sem_trywait

Standard C Library Functions                         sem_wait(3C)



NAME
     sem_wait, sem_trywait - acquire or wait for a semaphore

SYNOPSIS
     #include 

     int sem_wait(sem_t *sem);


     int sem_trywait(sem_t *sem);


DESCRIPTION
     The sem_wait() 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 sem_wait()
     until it either locks the semaphore or the  call  is  inter-
     rupted  by  a  signal.  The sem_trywait() 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 sem_post(3C) function is exe-
     cuted and returns successfully.


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

RETURN VALUES
     The sem_wait() and sem_trywait() 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.

ERRORS
     The  sem_wait() and sem_trywait() functions will fail if:

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


     ENOSYS     The sem_wait() and  sem_trywait()  functions  are
                not supported by the system.





SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                         sem_wait(3C)



     The  sem_trywait() function will fail if:

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



     The  sem_wait() and sem_trywait() 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
     sem_wait() and sem_trywait():

       #include 
       #define TELLERS 10
       sem_t  bank_line;      /* semaphore */
       int banking_hours(), deposit_withdrawal;
       void *customer(), do_business(), skip_banking_today();
       thread_t tid;
       ...

       sem_init(&bank_line,TRUE,TELLERS);  /* 10 tellers
                                              available */
       while(banking_hours())
               thr_create(NULL, NULL, customer,



SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                         sem_wait(3C)



                   (void *)deposit_withdrawal, THREAD_NEW_LWP, &tid);
       ...

       void *
       customer(deposit_withdrawal)
       void *deposit_withdrawal;
       {
           int this_customer, in_a_hurry = 50;
           this_customer = rand() % 100;
           if (this_customer == in_a_hurry)  {
               if (sem_trywait(&bank_line) != 0)
               if (errno == EAGAIN) {    /* no teller available */
                   skip_banking_today(this_customer);
                   return;
               }     /*else go immediately to available teller
                      & decrement bank_line*/
           }
           else
               sem_wait(&bank_line); /* wait for next teller,
                    then proceed, and decrement bank_line */
           do_business((int *)deposit_withdrawal);
           sem_getvalue(&bank_line,&num_tellers);
           sem_post(&bank_line); /* increment bank_line;
               this_customer's teller is now available */
       }


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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


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









SunOS 5.11           Last change: 5 Feb 2008                    3