msem_init(2)                                                   msem_init(2)




 NAME    [Toc]    [Back]
      msem_init - initialize a semaphore in a mapped file or anonymous
      memory region

 SYNOPSIS    [Toc]    [Back]
      #include <sys/mman.h>

      msemaphore *msem_init(msemaphore *sem, int initial_value);

 DESCRIPTION    [Toc]    [Back]
      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.

    Implementation Notes    [Toc]    [Back]
      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
      semaphore.

 RETURN VALUE    [Toc]    [Back]
      msem_init() returns the address of the initialized msemaphore



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 msem_init(2)                                                   msem_init(2)




      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.

 ERRORS    [Toc]    [Back]
      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
                          not valid.

           [ENOMEM]       A new semaphore could not be created.

           [EFAULT]       sem is an invalid pointer.

 AUTHOR    [Toc]    [Back]
      msem_init() was developed by HP and OSF.

 SEE ALSO    [Toc]    [Back]
      mmap(2), msem_lock(2), msem_remove(2), msem_unlock(2), mman(5).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      msem_init(): AES


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003