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. Clockbinsem 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 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 process that has locked a binary semaphore because it will be unable to clear the binsem->locked word before terminating.

Museum