sema_acq(2)                                           sema_acq(2)



NAME
     sema_acq, SEMA_TAS - attempt to exclusively acquire a
     semaphore

SYNOPSIS
     #include <sys/time.h>
     #include <sys/sema.h>

     int sema_acq(sem, timeout)
     semaphore *sem;
     struct timeval *timeout;

     int SEMA_TAS(sem)
     semaphore *sem;

DESCRIPTION
     sema_acq attempts to acquire exclusive access to the
     semaphore pointed to by sem.  If the semaphore is free, the
     acquisition is made entirely in the user context for
     efficiency.  When there is contention for the semaphore, a
     context switch to the kernel takes place.

     The parameter sem points to a semaphore as defined in
     <sys/sema.h>.  Before passing a new semaphore as an argument
     to sema_acq, you should set its values to 0.

     Normally, a semaphore resides in a memory segment that is
     shared with one or more processes. The shared segment must
     be attached at the same address in each of these processes
     (see shmat(2)).

     The SEMA_TAS macro performs an inline test of the semaphore
     pointed to by sem.  It returns 0 when the semaphore is
     acquired; otherwise it returns 1.  SEMA_TAS is provided for
     use in time-critical code sections, where no blocking or
     timeout is required.

     The timeout argument is used to specify a maximum time
     interval to wait for the semaphore to become free. If
     timeout is a null pointer, sem_acq can block the calling
     process for an indefinite period of time.  If timeout points
     to a zero-value timeval structure, the call does not block
     but returns a value of -1, setting errno to EWOULDBLOCK if
     the semaphore cannot be acquired immediately.

STATUS MESSAGES AND VALUES
     SEMA_TAS returns 0 when the semaphore is acquired; otherwise
     it returns 1.

     The sema_acq system call returns 0 on success or -1 if an
     error occurred.  If the time limit expires, sema_acq returns
     -1 with errno set to ETIME.  If sema_acq is interrupted



March 1993                                                      1

sema_acq(2)                                           sema_acq(2)



     before the specified timeout expires, the time remaining
     from the original timeout is returned in timeout.

     Upon an error, errno is set to one of the following values:

     EFAULT
          The sem or the timeout parameter points to an invalid
          location.

     EINTR
          A signal was delivered before the time limit expired
          and before the semaphore could be acquired.

     ETIME
          The timeout value specified by timeout expired before
          the semaphore could be acquired.

     EWOULDBLOCK
          The semaphore cannot be acquired without blocking.

SEE ALSO
     sema_rel(2), semget(2), shmat(2), shmget(2)

































2                                                      March 1993