lockbinsem(3C)                                     lockbinsem(3C)



NAME
     lockbinsem, clockbinsem - lock a binary semaphore

SYNOPSIS
     #include <sys/types.h>
     #include <sys/ipc.h>
     #include <sys/bsem.h>

     int lockbinsem (bsemid, binsem)
     int bsemid;
     struct binsem *binsem;

     int clockbinsem (bsemid, binsem)
     int bsemid;
     struct binsem *binsem;

DESCRIPTION
     Bsemid is a binary semaphore identifier obtained from a
     bsemget(2) call, and binsem is the address of the
     corresponding binary semaphore (which resides in shared
     memory (see shmget(2) and shmop(2))).

     lockbinsem returns with the binary semaphore locked.  If
     upon entry to lockbinsem the binary semaphore is locked,
     lockbinsem will block until the binary semaphore is
     unlocked.  Upon waking, lockbinsem will again attempt to
     lock the binary semaphore.

     Clockbinsem will lock the binary semaphore only if it can do
     so without blocking the caller.  Clockbinsem will return a
     value of 0 if the binary semaphore is locked successfully;
     or will return a value of 1 if the semaphore could not be
     locked without blocking the caller.

     lockbinsem and clockbinsem in conjunction with unlockbinsem
     can be used to control access to data shared by cooperating
     processes.  lockbinsem or clockbinsem is invoked prior to
     accessing the data to gain exclusive access to the data, and
     unlockbinsem is invoked after accessing the data to allow
     other processes to access the data.

RETURN VALUES
     Upon successful completion (i.e. binary semaphore locked),
     both lockbinsem and clockbinsem return zero values.  Clock-
     binsem will return a value of 1 when the binary semaphore
     can not be locked without blocking the caller.  Otherwise, a
     -1 is returned, and errno is set to indicate the error.  The
     errno returned will be that which is returned from the
     bsemwait(2) system service.

WARNING
     Both lockbinsem and clockbinsem deal with structures located



Page 1                        CX/UX Programmer's Reference Manual

lockbinsem(3C)                                     lockbinsem(3C)



     in user space (the binary semaphore being locked).  Error
     checking cannot occur unless the routines enter the kernel
     via the bsemwait(2) system service.  A bad binsem pointer
     will almost never be caught because an uninitialized data
     location will look like an unlocked binary semaphore (i.e.
     binsem->locked is set to 0) and the bsemwait(2) call will
     never take place.

     Additionally, users should not abnormally terminate a pro-
     cess that has locked a binary semaphore because it will be
     unable to clear the binsem->locked word before terminating.

SEE ALSO
     bsemwait(2), shmget(2), shmop(2), unlockbinsem(3C).









































Page 2                        CX/UX Programmer's Reference Manual