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

NAME

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

SYNOPSIS

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

DESCRIPTION

20       The  posix_typed_mem_open()  function  shall  establish  a   connection
21       between  the  typed memory object specified by the string pointed to by
22       name and a file descriptor. It shall create an  open  file  description
23       that  refers  to  the  typed  memory  object and a file descriptor that
24       refers to that open file description.  The  file  descriptor  shall  be
25       allocated  as described in Section 2.14, File Descriptor Allocation and
26       can be used by other functions to refer to that typed memory object. It
27       is unspecified whether the name appears in the file system and is visi‐
28       ble to other functions that take pathnames as arguments. The name argu‐
29       ment conforms to the construction rules for a pathname, except that the
30       interpretation of <slash> characters other  than  the  leading  <slash>
31       character in name is implementation-defined, and that the length limits
32       for the name argument are implementation-defined and need  not  be  the
33       same  as the pathname limits {PATH_MAX} and {NAME_MAX}.  If name begins
34       with    the    <slash>    character,     then     processes     calling
35       posix_typed_mem_open()  with  the same value of name shall refer to the
36       same typed memory object. If name does not begin with the <slash> char‐
37       acter, the effect is implementation-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.  The open file  description  is  new,  and
88       therefore  the  file  descriptor shall not share it with any other pro‐
89       cesses.  It  is  unspecified  whether  the  file  offset  is  set.  The
90       FD_CLOEXEC file descriptor flag associated with the new file descriptor
91       shall be cleared.
92
93       The behavior of msync(), ftruncate(), and  all  file  operations  other
94       than  mmap(),  posix_mem_offset(), posix_typed_mem_get_info(), fstat(),
95       dup(), dup2(), and close(), is unspecified when passed a file  descrip‐
96       tor connected to a typed memory object by this function.
97
98       The file status flags of the open file description shall be set accord‐
99       ing to the value of oflag.  Applications shall specify exactly  one  of
100       the  three  access  mode  values  described  below  and  defined in the
101       <fcntl.h> header, as the value of oflag.
102
103       O_RDONLY    Open for read access only.
104
105       O_WRONLY    Open for write access only.
106
107       O_RDWR      Open for read or write access.
108

RETURN VALUE

110       Upon successful completion, the posix_typed_mem_open()  function  shall
111       return  a non-negative integer representing the file descriptor. Other‐
112       wise, it shall return -1 and set errno to indicate the error.
113

ERRORS

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

EXAMPLES

150       None.
151

APPLICATION USAGE

153       None.
154

RATIONALE

156       None.
157

FUTURE DIRECTIONS

159       None.
160

SEE ALSO

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