sem_wait man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

SEM_WAIT(3C)							  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 per‐
       forming 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 sema‐
       phore 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 immedi‐
		  ately 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 sema‐
       phores.	 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  pro‐
       grammers	 must take into account the possibility of this kind of prior‐
       ity 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_try‐
       wait():

	 #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)

				  Feb 5, 2008			  SEM_WAIT(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net