Changeset 1ab6d59 in rtems-docs


Ignore:
Timestamp:
Jul 28, 2017, 6:45:01 PM (2 years ago)
Author:
Gedare Bloom <gedare@…>
Branches:
master
Children:
bbdf66c
Parents:
6543b90
git-author:
Gedare Bloom <gedare@…> (07/28/17 18:45:01)
git-committer:
Gedare Bloom <gedare@…> (07/28/17 19:15:57)
Message:

memory_management: update mmap, munmap, shm_open, shm_unlink

Close #2859.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • posix-users/memory_managment.rst

    r6543b90 r1ab6d59  
    168168.. code-block:: c
    169169
    170     int mmap(
    171     );
    172 
    173 **STATUS CODES:**
    174 
    175 .. list-table::
    176  :class: rtems-table
    177 
    178  * - ``E``
    179    - The
    180 
    181 **DESCRIPTION:**
    182 
    183 **NOTES:**
     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.
    184242
    185243.. _munmap:
     
    195253
    196254    int munmap(
    197     );
    198 
    199 **STATUS CODES:**
    200 
    201 .. list-table::
    202  :class: rtems-table
    203 
    204  * - ``E``
    205    - The
    206 
    207 **DESCRIPTION:**
     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.
    208279
    209280**NOTES:**
     
    273344
    274345    int shm_open(
    275     );
    276 
    277 **STATUS CODES:**
    278 
    279 .. list-table::
    280  :class: rtems-table
    281 
    282  * - ``E``
    283    - The
    284 
    285 **DESCRIPTION:**
    286 
    287 **NOTES:**
     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.
    288398
    289399.. _shm_unlink:
     
    299409
    300410    int shm_unlink(
    301     );
    302 
    303 **STATUS CODES:**
    304 
    305 .. list-table::
    306  :class: rtems-table
    307 
    308  * - ``E``
    309    - The
    310 
    311 **DESCRIPTION:**
    312 
    313 **NOTES:**
     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 TracChangeset for help on using the changeset viewer.