NAME

       posix_typed_mem_open - open a typed memory object (ADVANCED REALTIME)

SYNOPSIS

       #include <sys/mman.h>

       int posix_typed_mem_open(const char *name, int oflag, int tflag);

DESCRIPTION

       The  posix_typed_mem_open() function shall establish a connection between the typed memory
       object specified by the string pointed to by name and a file descriptor. It  shall  create
       an open file description that refers to the typed memory object and a file descriptor that
       refers to that open file description. The file descriptor is used by  other  functions  to
       refer  to that typed memory object. It is unspecified whether the name appears in the file
       system and is visible to other functions  that  take  pathnames  as  arguments.  The  name
       argument  shall  conform to the construction rules for a pathname. If name begins with the
       slash character, then processes calling posix_typed_mem_open() with the same value of name
       shall  refer  to  the  same  typed  memory  object.  If name does not begin with the slash
       character, the effect is implementation-defined. The interpretation  of  slash  characters
       other than the leading slash character in name is implementation-defined.

       Each  typed  memory  object  supported  in  a  system  shall be identified by a name which
       specifies not only its associated typed memory pool, but also the path or port by which it
       is  accessed.  That  is,  the  same typed memory pool accessed via several different ports
       shall have several different corresponding names. The  binding  between  names  and  typed
       memory  objects  is  established in an implementation-defined manner. Unlike shared memory
       objects, there is no way within IEEE Std 1003.1-2001 for  a  program  to  create  a  typed
       memory object.

       The  value  of tflag shall determine how the typed memory object behaves when subsequently
       mapped by calls to mmap(). At most, one of the following flags defined in <sys/mman.h> may
       be specified:

       POSIX_TYPED_MEM_ALLOCATE
              Allocate on mmap().

       POSIX_TYPED_MEM_ALLOCATE_CONTIG
              Allocate contiguously on mmap().

       POSIX_TYPED_MEM_MAP_ALLOCATABLE
              Map on mmap(), without affecting allocatability.

       If  tflag  has  the flag POSIX_TYPED_MEM_ALLOCATE specified, any subsequent call to mmap()
       using the returned file descriptor shall result in allocation and mapping of typed  memory
       from  the specified typed memory pool. The allocated memory may be a contiguous previously
       unallocated area of the typed memory pool or several non-contiguous previously unallocated
       areas  (mapped  to  a  contiguous portion of the process address space).  If tflag has the
       flag POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to  mmap()  using  the
       returned  file  descriptor  shall  result in allocation and mapping of a single contiguous
       previously unallocated area of the typed memory pool (also mapped to a contiguous  portion
       of the process address space).  If tflag has none of the flags POSIX_TYPED_MEM_ALLOCATE or
       POSIX_TYPED_MEM_ALLOCATE_CONTIG  specified,  any  subsequent  call  to  mmap()  using  the
       returned  file  descriptor  shall  map an application-chosen area from the specified typed
       memory pool such that this mapped area becomes unavailable for allocation  until  unmapped
       by  all  processes.  If  tflag has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, any
       subsequent call to mmap() using the returned file descriptor  shall  map  an  application-
       chosen  area from the specified typed memory pool without an effect on the availability of
       that area for allocation; that is, mapping such an object leaves each byte of  the  mapped
       area  unallocated  if  it  was  unallocated  prior  to  the mapping or allocated if it was
       allocated  prior  to   the   mapping.   The   appropriate   privilege   to   specify   the
       POSIX_TYPED_MEM_MAP_ALLOCATABLE flag is implementation-defined.

       If  successful, posix_typed_mem_open() shall return a file descriptor for the typed memory
       object that is the lowest numbered file descriptor not currently open  for  that  process.
       The  open  file  description  is new, and therefore the file descriptor shall not share it
       with any other processes. It is unspecified whether the file offset is set. The FD_CLOEXEC
       file descriptor flag associated with the new file descriptor shall be cleared.

       The  behavior  of  msync(),  ftruncate(),  and  all  file  operations  other  than mmap(),
       posix_mem_offset(), posix_typed_mem_get_info(), fstat(), dup(), dup2(),  and  close(),  is
       unspecified  when  passed  a  file  descriptor  connected to a typed memory object by this
       function.

       The file status flags of the open file description shall be set according to the value  of
       oflag.  Applications  shall  specify exactly one of the three access mode values described
       below and defined in the <fcntl.h> header, as the value of oflag.

       O_RDONLY
              Open for read access only.

       O_WRONLY
              Open for write access only.

       O_RDWR Open for read or write access.

RETURN VALUE

       Upon successful completion,  the  posix_typed_mem_open()  function  shall  return  a  non-
       negative  integer  representing  the lowest numbered unused file descriptor. Otherwise, it
       shall return -1 and set errno to indicate the error.

ERRORS

       The posix_typed_mem_open() function shall fail if:

       EACCES The typed memory object exists and the permissions specified by oflag are denied.

       EINTR  The posix_typed_mem_open() operation was interrupted by a signal.

       EINVAL The   flags   specified   in   tflag   are    invalid    (more    than    one    of
              POSIX_TYPED_MEM_ALLOCATE,            POSIX_TYPED_MEM_ALLOCATE_CONTIG,            or
              POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified).

       EMFILE Too many file descriptors are currently in use by this process.

       ENAMETOOLONG
              The length of the name argument exceeds  {PATH_MAX}  or  a  pathname  component  is
              longer than {NAME_MAX}.

       ENFILE Too many file descriptors are currently open in the system.

       ENOENT The named typed memory object does not exist.

       EPERM  The    caller    lacks    the   appropriate   privilege   to   specify   the   flag
              POSIX_TYPED_MEM_MAP_ALLOCATABLE in argument tflag.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       close() , dup() , exec()  ,  fcntl()  ,  fstat()  ,  ftruncate()  ,  mmap()  ,  msync()  ,
       posix_mem_offset() , posix_typed_mem_get_info() , umask() , the Base Definitions volume of
       IEEE Std 1003.1-2001, <fcntl.h>, <sys/mman.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .