[rtems-docs commit] memory_management: update mmap, munmap, shm_open, shm_unlink
Gedare Bloom
gedare at rtems.org
Fri Jul 28 19:16:07 UTC 2017
Module: rtems-docs
Branch: master
Commit: 1ab6d59863c17bd62a76517d434092f68d4ff8f3
Changeset: http://git.rtems.org/rtems-docs/commit/?id=1ab6d59863c17bd62a76517d434092f68d4ff8f3
Author: Gedare Bloom <gedare at rtems.org>
Date: Fri Jul 28 14:45:01 2017 -0400
memory_management: update mmap, munmap, shm_open, shm_unlink
Close #2859.
---
posix-users/memory_managment.rst | 149 ++++++++++++++++++++++++++++++++++++---
1 file changed, 140 insertions(+), 9 deletions(-)
diff --git a/posix-users/memory_managment.rst b/posix-users/memory_managment.rst
index 631ba45..ec3e60c 100644
--- a/posix-users/memory_managment.rst
+++ b/posix-users/memory_managment.rst
@@ -167,7 +167,13 @@ mmap - Map Process Addresses to a Memory Object
.. code-block:: c
- int mmap(
+ void *mmap(
+ void *addr,
+ size_t len,
+ int prot,
+ int flags,
+ int fildes,
+ off_t off
);
**STATUS CODES:**
@@ -175,13 +181,65 @@ mmap - Map Process Addresses to a Memory Object
.. list-table::
:class: rtems-table
- * - ``E``
- - The
+ * - ``EBADF``
+ - The fildes argument is not a valid open file descriptor.
+ * - ``EINVAL``
+ - The value of len is zero.
+ * - ``EINVAL``
+ - The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
+ * - ``EINVAL``
+ - The addr argument (if MAP_FIXED was specified) or off is not a multiple of
+ the page size as returned by sysconf(), or is considered invalid by the
+ implementation.
+ * - ``ENODEV``
+ - The fildes argument refers to a file whose type is not supported by mmap.
+ * - ``ENOMEM``
+ - MAP_FIXED was specified, and the range [addr,addr+len) exceeds that
+ allowed for the address space of a process; or, if MAP_FIXED was not
+ specified and there is insufficient room in the address space to effect
+ the mapping.
+ * - ``ENOTSUP``
+ - MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the
+ implementation does not support this functionality.
+ * - ``ENOTSUP``
+ - The implementation does not support the combination of accesses requested
+ in the prot argument.
+ * - ``ENXIO``
+ - Addresses in the range [off,off+len) are invalid for the object specified
+ by fildes.
+ * - ``ENXIO``
+ - MAP_FIXED was specified in flags and the combination of addr, len, and off
+ is invalid for the object specified by fildes.
+ * - ``EOVERFLOW``
+ - The file is a regular file and the value of off plus len exceeds the
+ offset maximum established in the open file description associated with
+ fildes.
**DESCRIPTION:**
+``mmap`` establishes a mapping between an address ``pa`` for ``len`` bytes to
+the memory object represented by the file descriptor ``fildes`` at offset
+``off`` for ``len`` bytes. The value of ``pa`` is an implementation-defined
+function of the parameter addr and the values of ``flags``. A successful
+``mmap()`` call shall return ``pa`` as its result. An unsuccessful call returns
+``MAP_FAILED`` and sets ``errno`` accordingly.
+
**NOTES:**
+RTEMS is a single address space operating system without privilege separation
+between the kernel and user space. Therefore, the implementation of ``mmap``
+has a number of implementation-specific issues to be aware of:
+ * Read, write and execute permissions are allowed because the memory in RTEMS
+ does not normally have protections but we cannot hide access to memory.
+ Thus, the use of ``PROT_NONE`` for the ``prot`` argument is not supported.
+ Similarly, there is no restriction of write access, so ``PROT_WRITE`` must
+ be in the ``prot`` argument.
+ * Anonymous mappings must have ``fildes`` set to -1 and ``off`` set to 0.
+ Shared mappings are not supported with Anonymous mappings.
+ * ``MAP_FIXED`` is not supported for shared memory objects with ``MAP_SHARED``.
+ * Support for shared mappings is dependent on the underlying object's
+ filesystem implementation of an ``mmap_h`` file operation handler.
+
.. _munmap:
munmap - Unmap Previously Mapped Addresses
@@ -194,6 +252,8 @@ munmap - Unmap Previously Mapped Addresses
.. code-block:: c
int munmap(
+ void *addr,
+ size_t len
);
**STATUS CODES:**
@@ -201,11 +261,22 @@ munmap - Unmap Previously Mapped Addresses
.. list-table::
:class: rtems-table
- * - ``E``
- - The
+ * - ``EINVAL``
+ - Addresses in the range [addr,addr+len) are outside the valid range for the
+ address space.
+ * - ``EINVAL``
+ - The len argument is 0.
**DESCRIPTION:**
+The ``munmap()`` function shall remove any mappings for those entire pages
+containing any part of the address space of the process starting at ``addr``
+and continuing for ``len`` bytes. If there are no mappings in the specified
+address range, then ``munmap()`` has no effect.
+
+Upon successful completion, ``munmap()`` shall return 0; otherwise, it shall
+return -1 and set ``errno`` to indicate the error.
+
**NOTES:**
.. _mprotect:
@@ -272,6 +343,9 @@ shm_open - Open a Shared Memory Object
.. code-block:: c
int shm_open(
+ const char *name,
+ int oflag,
+ mode_t mode
);
**STATUS CODES:**
@@ -279,13 +353,49 @@ shm_open - Open a Shared Memory Object
.. list-table::
:class: rtems-table
- * - ``E``
- - The
+ * - ``EACCES``
+ - The shared memory object exists and the permissions specified by oflag are
+ denied, or the shared memory object does not exist and permission to
+ create the shared memory object is denied, or O_TRUNC is specified and
+ write permission is denied.
+ * - ``EEXIST``
+ - O_CREAT and O_EXCL are set and the named shared memory object already
+ exists.
+ * - ``EINVAL``
+ - The ``shm_open()`` operation is not supported for the given name.
+ * - ``EMFILE``
+ - All file descriptors available to the process are currently open.
+ * - ``ENFILE``
+ - Too many shared memory objects are currently open in the system.
+ * - ``ENOENT``
+ - O_CREAT is not set and the named shared memory object does not exist.
+ * - ``ENOSPC``
+ - There is insufficient space for the creation of the new shared memory
+ object.
+ * - ``ENAMETOOLONG``
+ - The length of the name argument exceeds ``_POSIX_PATH_MAX``.
+
**DESCRIPTION:**
+The ``shm_open()`` function shall establish a connection between a shared
+memory object and a file descriptor. It shall create an open file description
+that refers to the shared memory object and a file descriptor that refers to
+that open file description. The ``name`` argument points to a string naming a
+shared memory object.
+
+If successful, ``shm_open()`` shall return a file descriptor for the shared
+memory object. Upon successful completion, the ``shm_open()`` function shall
+return a non-negative integer representing the file descriptor. Otherwise, it
+shall return -1 and set ``errno`` to indicate the error.
+
**NOTES:**
+An application can set the ``_POSIX_Shm_Object_operations`` to control the
+behavior of shared memory objects when accessed via the file descriptor.
+
+The ``name`` must be valid for an RTEMS SuperCore Object.
+
.. _shm_unlink:
shm_unlink - Remove a Shared Memory Object
@@ -298,6 +408,7 @@ shm_unlink - Remove a Shared Memory Object
.. code-block:: c
int shm_unlink(
+ const char *name
);
**STATUS CODES:**
@@ -305,9 +416,29 @@ shm_unlink - Remove a Shared Memory Object
.. list-table::
:class: rtems-table
- * - ``E``
- - The
+ * - ``ENOENT``
+ - The named shared memory object does not exist.
+ * - ``ENAMETOOLONG``
+ - The length of the name argument exceeds ``_POSIX_PATH_MAX``.
**DESCRIPTION:**
+The ``shm_unlink()`` function shall remove the name of the shared memory object
+named by the string pointed to by ``name``.
+
+If one or more references to the shared memory object exist when the object is
+unlinked, the name shall be removed before ``shm_unlink()`` returns, but the
+removal of the memory object contents shall be postponed until all open and map
+references to the shared memory object have been removed.
+
+Even if the object continues to exist after the last ``shm_unlink()``, reuse of
+the name shall subsequently cause ``shm_open()`` to behave as if no shared
+memory object of this name exists.
+
+Upon successful completion, a value of zero shall be returned. Otherwise, a
+value of -1 shall be returned and errno set to indicate the error. If -1 is
+returned, the named shared memory object shall not be changed by this function
+call.
+
**NOTES:**
+
More information about the vc
mailing list