source: rtems-docs/posix-users/memory_managment.rst @ 1ab6d59

5am
Last change on this file since 1ab6d59 was 1ab6d59, checked in by Gedare Bloom <gedare@…>, on 07/28/17 at 18:45:01

memory_management: update mmap, munmap, shm_open, shm_unlink

Close #2859.

  • Property mode set to 100644
File size: 10.7 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2002.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7Memory Management Manager
8#########################
9
10Introduction
11============
12
13The
14memory management manager is ...
15
16The directives provided by the memory management manager are:
17
18- mlockall_ - Lock the Address Space of a Process
19
20- munlockall_ - Unlock the Address Space of a Process
21
22- mlock_ - Lock a Range of the Process Address Space
23
24- munlock_ - Unlock a Range of the Process Address Space
25
26- mmap_ - Map Process Addresses to a Memory Object
27
28- munmap_ - Unmap Previously Mapped Addresses
29
30- mprotect_ - Change Memory Protection
31
32- msync_ - Memory Object Synchronization
33
34- shm_open_ - Open a Shared Memory Object
35
36- shm_unlink_ - Remove a Shared Memory Object
37
38Background
39==========
40
41There is currently no text in this section.
42
43Operations
44==========
45
46There is currently no text in this section.
47
48Directives
49==========
50
51This section details the memory management manager's directives.  A subsection
52is dedicated to each of this manager's directives and describes the calling
53sequence, related constants, usage, and status codes.
54
55.. _mlockall:
56
57mlockall - Lock the Address Space of a Process
58----------------------------------------------
59.. index:: mlockall
60.. index:: lock the address space of a process
61
62**CALLING SEQUENCE:**
63
64.. code-block:: c
65
66    int mlockall(
67    );
68
69**STATUS CODES:**
70
71.. list-table::
72 :class: rtems-table
73
74 * - ``E``
75   - The
76
77**DESCRIPTION:**
78
79**NOTES:**
80
81.. _munlockall:
82
83munlockall - Unlock the Address Space of a Process
84--------------------------------------------------
85.. index:: munlockall
86.. index:: unlock the address space of a process
87
88**CALLING SEQUENCE:**
89
90.. code-block:: c
91
92    int munlockall(
93    );
94
95**STATUS CODES:**
96
97.. list-table::
98 :class: rtems-table
99
100 * - ``E``
101   - The
102
103**DESCRIPTION:**
104
105**NOTES:**
106
107.. _mlock:
108
109mlock - Lock a Range of the Process Address Space
110-------------------------------------------------
111.. index:: mlock
112.. index:: lock a range of the process address space
113
114**CALLING SEQUENCE:**
115
116.. code-block:: c
117
118    int mlock(
119    );
120
121**STATUS CODES:**
122
123.. list-table::
124 :class: rtems-table
125
126 * - ``E``
127   - The
128
129**DESCRIPTION:**
130
131**NOTES:**
132
133.. _munlock:
134
135munlock - Unlock a Range of the Process Address Space
136-----------------------------------------------------
137.. index:: munlock
138.. index:: unlock a range of the process address space
139
140**CALLING SEQUENCE:**
141
142.. code-block:: c
143
144    int munlock(
145    );
146
147**STATUS CODES:**
148
149.. list-table::
150 :class: rtems-table
151
152 * - ``E``
153   - The
154
155**DESCRIPTION:**
156
157**NOTES:**
158
159.. _mmap:
160
161mmap - Map Process Addresses to a Memory Object
162-----------------------------------------------
163.. index:: mmap
164.. index:: map process addresses to a memory object
165
166**CALLING SEQUENCE:**
167
168.. code-block:: c
169
170    void *mmap(
171        void *addr,
172        size_t len,
173        int prot,
174        int flags,
175        int fildes,
176        off_t off
177    );
178
179**STATUS CODES:**
180
181.. list-table::
182 :class: rtems-table
183
184 * - ``EBADF``
185   - The fildes argument is not a valid open file descriptor.
186 * - ``EINVAL``
187   - The value of len is zero.
188 * - ``EINVAL``
189   - The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
190 * - ``EINVAL``
191   - The addr argument (if MAP_FIXED was specified) or off is not a multiple of
192     the page size as returned by sysconf(), or is considered invalid by the
193     implementation.
194 * - ``ENODEV``
195   - The fildes argument refers to a file whose type is not supported by mmap.
196 * - ``ENOMEM``
197   - MAP_FIXED was specified, and the range [addr,addr+len) exceeds that
198     allowed for the address space of a process; or, if MAP_FIXED was not
199     specified and there is insufficient room in the address space to effect
200     the mapping.
201 * - ``ENOTSUP``
202   - MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the
203     implementation does not support this functionality.
204 * - ``ENOTSUP``
205   - The implementation does not support the combination of accesses requested
206     in the prot argument.
207 * - ``ENXIO``
208   - Addresses in the range [off,off+len) are invalid for the object specified
209     by fildes.
210 * - ``ENXIO``
211   - MAP_FIXED was specified in flags and the combination of addr, len, and off
212     is invalid for the object specified by fildes.
213 * - ``EOVERFLOW``
214   - The file is a regular file and the value of off plus len exceeds the
215     offset maximum established in the open file description associated with
216     fildes.
217
218**DESCRIPTION:**
219
220``mmap`` establishes a mapping between an address ``pa`` for ``len`` bytes to
221the memory object represented by the file descriptor ``fildes`` at offset
222``off`` for ``len`` bytes.  The value of ``pa`` is an implementation-defined
223function of the parameter addr and the values of ``flags``. A successful
224``mmap()`` call shall return ``pa`` as its result. An unsuccessful call returns
225``MAP_FAILED`` and sets ``errno`` accordingly.
226
227**NOTES:**
228
229RTEMS is a single address space operating system without privilege separation
230between the kernel and user space. Therefore, the implementation of ``mmap``
231has a number of implementation-specific issues to be aware of:
232 * Read, write and execute permissions are allowed because the memory in RTEMS
233   does not normally have protections but we cannot hide access to memory.
234   Thus, the use of ``PROT_NONE`` for the ``prot`` argument is not supported.
235   Similarly, there is no restriction of write access, so ``PROT_WRITE`` must
236   be in the ``prot`` argument.
237 * Anonymous mappings must have ``fildes`` set to -1 and ``off`` set to 0.
238   Shared mappings are not supported with Anonymous mappings.
239 * ``MAP_FIXED`` is not supported for shared memory objects with ``MAP_SHARED``.
240 * Support for shared mappings is dependent on the underlying object's
241   filesystem implementation of an ``mmap_h`` file operation handler.
242
243.. _munmap:
244
245munmap - Unmap Previously Mapped Addresses
246------------------------------------------
247.. index:: munmap
248.. index:: unmap previously mapped addresses
249
250**CALLING SEQUENCE:**
251
252.. code-block:: c
253
254    int munmap(
255        void *addr,
256        size_t len
257    );
258
259**STATUS CODES:**
260
261.. list-table::
262 :class: rtems-table
263
264 * - ``EINVAL``
265   - Addresses in the range [addr,addr+len) are outside the valid range for the
266     address space.
267 * - ``EINVAL``
268   - The len argument is 0.
269
270**DESCRIPTION:**
271
272The ``munmap()`` function shall remove any mappings for those entire pages
273containing any part of the address space of the process starting at ``addr``
274and continuing for ``len`` bytes.  If there are no mappings in the specified
275address range, then ``munmap()`` has no effect.
276
277Upon successful completion, ``munmap()`` shall return 0; otherwise, it shall
278return -1 and set ``errno`` to indicate the error.
279
280**NOTES:**
281
282.. _mprotect:
283
284mprotect - Change Memory Protection
285-----------------------------------
286.. index:: mprotect
287.. index:: change memory protection
288
289**CALLING SEQUENCE:**
290
291.. code-block:: c
292
293    int mprotect(
294    );
295
296**STATUS CODES:**
297
298.. list-table::
299 :class: rtems-table
300
301 * - ``E``
302   - The
303
304**DESCRIPTION:**
305
306**NOTES:**
307
308.. _msync:
309
310msync - Memory Object Synchronization
311-------------------------------------
312.. index:: msync
313.. index:: memory object synchronization
314
315**CALLING SEQUENCE:**
316
317.. code-block:: c
318
319    int msync(
320    );
321
322**STATUS CODES:**
323
324.. list-table::
325 :class: rtems-table
326
327 * - ``E``
328   - The
329
330**DESCRIPTION:**
331
332**NOTES:**
333
334.. _shm_open:
335
336shm_open - Open a Shared Memory Object
337--------------------------------------
338.. index:: shm_open
339.. index:: open a shared memory object
340
341**CALLING SEQUENCE:**
342
343.. code-block:: c
344
345    int shm_open(
346        const char *name,
347        int oflag,
348        mode_t mode
349    );
350
351**STATUS CODES:**
352
353.. list-table::
354 :class: rtems-table
355
356 * - ``EACCES``
357   - The shared memory object exists and the permissions specified by oflag are
358     denied, or the shared memory object does not exist and permission to
359     create the shared memory object is denied, or O_TRUNC is specified and
360     write permission is denied.
361 * - ``EEXIST``
362   - O_CREAT and O_EXCL are set and the named shared memory object already
363     exists.
364 * - ``EINVAL``
365   - The ``shm_open()`` operation is not supported for the given name.
366 * - ``EMFILE``
367   - All file descriptors available to the process are currently open.
368 * - ``ENFILE``
369   - Too many shared memory objects are currently open in the system.
370 * - ``ENOENT``
371   - O_CREAT is not set and the named shared memory object does not exist.
372 * - ``ENOSPC``
373   - There is insufficient space for the creation of the new shared memory
374     object.
375 * - ``ENAMETOOLONG``
376   - The length of the name argument exceeds ``_POSIX_PATH_MAX``.
377
378
379**DESCRIPTION:**
380
381The ``shm_open()`` function shall establish a connection between a shared
382memory object and a file descriptor. It shall create an open file description
383that refers to the shared memory object and a file descriptor that refers to
384that open file description. The ``name`` argument points to a string naming a
385shared memory object.
386
387If successful, ``shm_open()`` shall return a file descriptor for the shared
388memory object. Upon successful completion, the ``shm_open()`` function shall
389return a non-negative integer representing the file descriptor. Otherwise, it
390shall return -1 and set ``errno`` to indicate the error.
391
392**NOTES:**
393
394An application can set the ``_POSIX_Shm_Object_operations`` to control the
395behavior of shared memory objects when accessed via the file descriptor.
396
397The ``name`` must be valid for an RTEMS SuperCore Object.
398
399.. _shm_unlink:
400
401shm_unlink - Remove a Shared Memory Object
402------------------------------------------
403.. index:: shm_unlink
404.. index:: remove a shared memory object
405
406**CALLING SEQUENCE:**
407
408.. code-block:: c
409
410    int shm_unlink(
411        const char *name
412    );
413
414**STATUS CODES:**
415
416.. list-table::
417 :class: rtems-table
418
419 * - ``ENOENT``
420   - The named shared memory object does not exist.
421 * - ``ENAMETOOLONG``
422   - The length of the name argument exceeds ``_POSIX_PATH_MAX``.
423
424**DESCRIPTION:**
425
426The ``shm_unlink()`` function shall remove the name of the shared memory object
427named by the string pointed to by ``name``.
428
429If one or more references to the shared memory object exist when the object is
430unlinked, the name shall be removed before ``shm_unlink()`` returns, but the
431removal of the memory object contents shall be postponed until all open and map
432references to the shared memory object have been removed.
433
434Even if the object continues to exist after the last ``shm_unlink()``, reuse of
435the name shall subsequently cause ``shm_open()`` to behave as if no shared
436memory object of this name exists.
437
438Upon successful completion, a value of zero shall be returned. Otherwise, a
439value of -1 shall be returned and errno set to indicate the error. If -1 is
440returned, the named shared memory object shall not be changed by this function
441call.
442
443**NOTES:**
444
Note: See TracBrowser for help on using the repository browser.