msem_init - initialize a semaphore in a mapped file or anonymous
msemaphore *msem_init(msemaphore *sem, int initial_value);
msem_init() allocates a new binary semaphore and initializes the state
of the new semaphore.
sem points to an msemaphore structure in which the state of the
semaphore is to be stored.
If initial_value is MSEM_LOCKED, the new semaphore is initialized in
the locked state. If initial_value is MSEM_UNLOCKED, the new
semaphore is initialized in the unlocked state.
The msemaphore structure must be located within a mapped file or
anonymous memory region created by a successful call to mmap() and
have both read and write access.
If a semaphore is created in a mapped file region, any reference by a
process that has mapped the same file, using a (struct msemaphore *)
pointer that resolves to the same file offset is interpreted as a
reference to the same semaphore. If a semaphore is created in an
anonymous memory region, any reference by a process sharing the same
region by use of a (struct msemaphore *) pointer that resolves to the
same offset from the start of the region is interpreted as a reference
to the same semaphore.
Any previous semaphore state stored in the msemaphore structure will
be ignored and overwritten.
In order to ensure that an msemaphore structure is entirely contained
in a single memory page, sem must be at an address that is an exact
multiple of sizeof(struct msemaphore). The size of the msemaphore
structure is guaranteed to prevent semaphores that cross page
boundaries given the above restriction.
For a memory mapped file region, the system deallocates memory that
corresponds to a range of the file that has been truncated with
ftruncate() or truncate(). If a semaphore is located in memory so
deallocated, the effect is equivalent to an msem_remove() on the
msem_init() returns the address of the initialized msemaphore
Hewlett-Packard Company - 1 - HP-UX Release 11i: November 2000
structure; otherwise, it returns NULL and sets errno to indicate the
error. NOTE: This error return value may change to -1 in a future
HP-UX release. For portability, applications should check for a zero
or negative value for error returns.
msem_init() fails if any of the following conditions are encountered:
[EINVAL] sem points to an msemaphore structure that is not
located in a mapped region created by mmap() and
with read and write access, or initial_value is
[ENOMEM] A new semaphore could not be created.
[EFAULT] sem is an invalid pointer.
msem_init() was developed by HP and OSF.
mmap(2), msem_lock(2), msem_remove(2), msem_unlock(2), mman(5).
Hewlett-Packard Company - 2 - HP-UX Release 11i: November 2000