sem_wait(3C)						   Standard C Library Functions 					      sem_wait(3C)

NAME

       sem_wait, sem_trywait - acquire or wait for a semaphore

SYNOPSIS

       #include <semaphore.h>

       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 semaphore. 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  interrupted  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 semaphore.

       Upon successful return, the state of the semaphore is locked and remains locked until the sem_post(3C) function	is  executed  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 sem-
       aphore 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 semaphore.

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

       The  sem_trywait() function will fail if:

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

       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 pre-
       empted by a medium priority 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, realtime 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 analogous to the synchronization scheme of a semaphore utilizing sem_wait() and
       sem_trywait():

	 #include <errno.h>
	 #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,
		     (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 attributes:

       +-----------------------------+-----------------------------+
       |      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							    5 Feb 2008							      sem_wait(3C)