1POSIX_TYPED_MEM_OPEN(3P)   POSIX Programmer's Manual  POSIX_TYPED_MEM_OPEN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       posix_typed_mem_open — open a typed memory object (ADVANCED REALTIME)
14

SYNOPSIS

16       #include <sys/mman.h>
17
18       int posix_typed_mem_open(const char *name, int oflag, int tflag);
19

DESCRIPTION

21       The  posix_typed_mem_open()  function  shall  establish  a   connection
22       between  the  typed memory object specified by the string pointed to by
23       name and a file descriptor. It shall create an  open  file  description
24       that  refers  to  the  typed  memory  object and a file descriptor that
25       refers to that open file description. The file descriptor  is  used  by
26       other functions to refer to that typed memory object. It is unspecified
27       whether the name appears in the file system and  is  visible  to  other
28       functions  that take pathnames as arguments. The name argument conforms
29       to the construction rules for a pathname, except that  the  interpreta‐
30       tion  of <slash> characters other than the leading <slash> character in
31       name is implementation-defined, and that the length limits for the name
32       argument  are  implementation-defined  and  need not be the same as the
33       pathname limits {PATH_MAX} and {NAME_MAX}.  If  name  begins  with  the
34       <slash>  character,  then processes calling posix_typed_mem_open() with
35       the same value of name shall refer to the same typed memory object.  If
36       name does not begin with the <slash> character, the effect is implemen‐
37       tation-defined.
38
39       Each typed memory object supported in a system shall be identified by a
40       name  which  specifies  not  only its associated typed memory pool, but
41       also the path or port by which it is accessed. That is, the same  typed
42       memory  pool  accessed  via  several different ports shall have several
43       different corresponding names. The binding between names and typed mem‐
44       ory  objects is established in an implementation-defined manner. Unlike
45       shared memory objects, there is no way within POSIX.1‐2008 for  a  pro‐
46       gram to create a typed memory object.
47
48       The  value of tflag shall determine how the typed memory object behaves
49       when subsequently mapped by calls to mmap().  At most, one of the  fol‐
50       lowing flags defined in <sys/mman.h> may be specified:
51
52       POSIX_TYPED_MEM_ALLOCATE
53             Allocate on mmap().
54
55       POSIX_TYPED_MEM_ALLOCATE_CONTIG
56             Allocate contiguously on mmap().
57
58       POSIX_TYPED_MEM_MAP_ALLOCATABLE
59             Map on mmap(), without affecting allocatability.
60
61       If  tflag  has  the flag POSIX_TYPED_MEM_ALLOCATE specified, any subse‐
62       quent call to mmap() using the returned file descriptor shall result in
63       allocation  and mapping of typed memory from the specified typed memory
64       pool. The allocated memory may be a contiguous  previously  unallocated
65       area  of  the  typed  memory  pool or several non-contiguous previously
66       unallocated areas (mapped  to  a  contiguous  portion  of  the  process
67       address  space).  If tflag has the flag POSIX_TYPED_MEM_ALLOCATE_CONTIG
68       specified, any subsequent  call  to  mmap()  using  the  returned  file
69       descriptor  shall result in allocation and mapping of a single contigu‐
70       ous previously unallocated area of the typed memory pool  (also  mapped
71       to  a  contiguous  portion  of the process address space). If tflag has
72       none of the  flags  POSIX_TYPED_MEM_ALLOCATE  or  POSIX_TYPED_MEM_ALLO‐
73       CATE_CONTIG specified, any subsequent call to mmap() using the returned
74       file descriptor shall map an application-chosen area from the specified
75       typed  memory  pool  such that this mapped area becomes unavailable for
76       allocation until unmapped by all  processes.  If  tflag  has  the  flag
77       POSIX_TYPED_MEM_MAP_ALLOCATABLE   specified,  any  subsequent  call  to
78       mmap() using the returned file descriptor shall map an application-cho‐
79       sen  area from the specified typed memory pool without an effect on the
80       availability of that area for allocation;  that  is,  mapping  such  an
81       object  leaves each byte of the mapped area unallocated if it was unal‐
82       located prior to the mapping or allocated if it was allocated prior  to
83       the     mapping.     Appropriate     privileges    to    specify    the
84       POSIX_TYPED_MEM_MAP_ALLOCATABLE flag are implementation-defined.
85
86       If successful, posix_typed_mem_open() shall return  a  file  descriptor
87       for the typed memory object that is the lowest numbered file descriptor
88       not currently open for that process.  The open file description is new,
89       and  therefore  the  file  descriptor shall not share it with any other
90       processes. It is unspecified  whether  the  file  offset  is  set.  The
91       FD_CLOEXEC file descriptor flag associated with the new file descriptor
92       shall be cleared.
93
94       The behavior of msync(), ftruncate(), and  all  file  operations  other
95       than  mmap(),  posix_mem_offset(), posix_typed_mem_get_info(), fstat(),
96       dup(), dup2(), and close(), is unspecified when passed a file  descrip‐
97       tor connected to a typed memory object by this function.
98
99       The file status flags of the open file description shall be set accord‐
100       ing to the value of oflag.  Applications shall specify exactly  one  of
101       the  three  access  mode  values  described  below  and  defined in the
102       <fcntl.h> header, as the value of oflag.
103
104       O_RDONLY    Open for read access only.
105
106       O_WRONLY    Open for write access only.
107
108       O_RDWR      Open for read or write access.
109

RETURN VALUE

111       Upon successful completion, the posix_typed_mem_open()  function  shall
112       return  a  non-negative integer representing the lowest numbered unused
113       file descriptor. Otherwise, it shall return −1 and set errno  to  indi‐
114       cate the error.
115

ERRORS

117       The posix_typed_mem_open() function shall fail if:
118
119       EACCES The  typed memory object exists and the permissions specified by
120              oflag are denied.
121
122       EINTR  The posix_typed_mem_open() operation was interrupted by  a  sig‐
123              nal.
124
125       EINVAL The flags specified in tflag are invalid (more than one of
126              POSIX_TYPED_MEM_ALLOCATE, POSIX_TYPED_MEM_ALLOCATE_CONTIG, or
127              POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified).
128
129       EMFILE All  file  descriptors  available  to  the process are currently
130              open.
131
132       ENFILE Too many file descriptors are currently open in the system.
133
134       ENOENT The named typed memory object does not exist.
135
136       EPERM  The  caller  lacks  appropriate  privileges   to   specify   the
137              POSIX_TYPED_MEM_MAP_ALLOCATABLE flag in the tflag argument.
138
139       The posix_typed_mem_open() function may fail if:
140
141       ENAMETOOLONG
142              The  length  of  the  name argument exceeds {_POSIX_PATH_MAX} on
143              systems  that  do  not  support  the  XSI  option   or   exceeds
144              {_XOPEN_PATH_MAX}  on  XSI  systems, or has a pathname component
145              that is longer than {_POSIX_NAME_MAX} on  systems  that  do  not
146              support  the  XSI option or longer than {_XOPEN_NAME_MAX} on XSI
147              systems.
148
149       The following sections are informative.
150

EXAMPLES

152       None.
153

APPLICATION USAGE

155       None.
156

RATIONALE

158       None.
159

FUTURE DIRECTIONS

161       None.
162

SEE ALSO

164       close(), dup(), exec, fcntl(), fstat(), ftruncate(),  mmap(),  msync(),
165       posix_mem_offset(), posix_typed_mem_get_info(), umask()
166
167       The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <sys_mman.h>
168
170       Portions  of  this text are reprinted and reproduced in electronic form
171       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
172       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
173       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
174       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
175       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
176       event of any discrepancy between this version and the original IEEE and
177       The Open Group Standard, the original IEEE and The Open Group  Standard
178       is  the  referee document. The original Standard can be obtained online
179       at http://www.unix.org/online.html .
180
181       Any typographical or formatting errors that appear  in  this  page  are
182       most likely to have been introduced during the conversion of the source
183       files to man page format. To report such errors,  see  https://www.ker
184       nel.org/doc/man-pages/reporting_bugs.html .
185
186
187
188IEEE/The Open Group                  2013             POSIX_TYPED_MEM_OPEN(3P)
Impressum