======================== Shared Memory Interfaces ======================== Shared memory interfaces are only available with the NuttX kernel build (``CONFIG_BUILD_KERNEL=y``). These interfaces support user memory regions that can be shared between multiple user processes. Shared memory interfaces: - :c:func:`shmget` - :c:func:`shmat` - :c:func:`shmctl` - :c:func:`shmdt` Functions ========= .. c:function:: int shmget(key_t key, size_t size, int shmflg) Returns the shared memory identifier associated with ``key``. A shared memory identifier, associated data structure, and shared memory segment of at least size bytes is created for ``key`` if one of the following is true: - The argument ``key`` is equal to ``IPC_PRIVATE``. - The argument ``key`` does not already have a shared memory identifier associated with it and ``(shmflg & IPC_CREAT)`` is non-zero. Upon creation, the data structure associated with the new shared memory identifier will be initialized as follows: - The low-order nine bits of ``shm_perm.mode`` are set equal to the low-order nine bits of ``shmflg``. - The value of ``shm_segsz`` is set equal to the value of size. - The values of ``shm_lpid``, ``shm_nattch``, ``shm_atime``, and ``shm_dtime`` are set equal to 0. - The value of ``shm_ctime`` is set equal to the current time. When the shared memory segment is created, it will be initialized with all zero values. :param key: The key that is used to access the unique shared memory identifier. :param size: The shared memory region that is created will be at least this size in bytes. :param shmflg: See ``IPC_*`` definitions in ``sys/ipc.h``. Only the values ``IPC_PRIVATE`` or ``IPC_CREAT`` are supported. :return: Upon successful completion, ``shmget()`` will return a non-negative integer, namely a shared memory identifier; otherwise, it will return -1 and set ``errno`` to indicate the error. - ``EACCES``. A shared memory identifier exists for key but operation permission as specified by the low-order nine bits of ``shmflg`` would not be granted. - ``EEXIST``. A shared memory identifier exists for the argument key but ``(shmflg & IPC_CREAT) && (shmflg & IPC_EXCL)`` are non-zero. - ``EINVAL``. A shared memory segment is to be created and the value of size is less than the system-imposed minimum or greater than the system-imposed maximum. - ``EINVAL``. No shared memory segment is to be created and a shared memory segment exists for key but the size of the segment associated with it is less than size and size is not 0. - ``ENOENT``. A shared memory identifier does not exist for the argument key and ``(shmflg & IPC_CREAT)`` is 0. - ``ENOMEM``. A shared memory identifier and associated shared memory segment will be created, but the amount of available physical memory is not sufficient to fill the request. - ``ENOSPC``. A shared memory identifier is to be created, but the system-imposed limit on the maximum number of allowed shared memory identifiers system-wide would be exceeded. **POSIX Deviations** - The values of ``shm_perm.cuid``, ``shm_perm.uid``, ``shm_perm.cgid``, and ``shm_perm.gid`` should be set equal to the effective user ID and effective group ID, respectively, of the calling process. The NuttX ``ipc_perm`` structure, however, does not support these fields because user and group IDs are not yet supported by NuttX. .. c:function:: void *shmat(int shmid, FAR const void *shmaddr, int shmflg) Attaches the shared memory segment associated with the shared memory identifier specified by ``shmid`` to the address space of the calling process. The segment is attached at the address specified by one of the following criteria: - If ``shmaddr`` is a null pointer, the segment is attached at the first available address as selected by the system. - If ``shmaddr`` is not a null pointer and ``(shmflg & SHM_RND)`` is non-zero, the segment is attached at the address given by ``(shmaddr - ((uintptr_t)shmaddr % SHMLBA))``. - If ``shmaddr`` is not a null pointer and ``(shmflg & SHM_RND)`` is 0, the segment is attached at the address given by ``shmaddr``. - The segment is attached for reading if ``(shmflg & SHM_RDONLY)`` is non-zero and the calling process has read permission; otherwise, if it is 0 and the calling process has read and write permission, the segment is attached for reading and writing. :param shmid: Shared memory identifier :param smaddr: Determines mapping of the shared memory region :param shmflg: See ``SHM_*`` definitions in ``include/sys/shm.h``. Only ``SHM_RDONLY`` and ``SHM_RND`` are supported. :return: Upon successful completion, ``shmat()`` will increment the value of ``shm_nattch`` in the data structure associated with the shared memory ID of the attached shared memory segment and return the segment's start address. Otherwise, the shared memory segment will not be attached, ``shmat()`` will return -1, and ``errno`` will be set to indicate the error. - ``EACCES``. Operation permission is denied to the calling process - ``EINVAL``. The value of ``shmid`` is not a valid shared memory identifier, the ``shmaddr`` is not a null pointer, and the value of ``(shmaddr -((uintptr_t)shmaddr % SHMLBA))`` is an illegal address for attaching shared memory; or the ``shmaddr`` is not a null pointer, ``(shmflg & SHM_RND)`` is 0, and the value of ``shmaddr`` is an illegal address for attaching shared memory. - ``EMFILE``. The number of shared memory segments attached to the calling process would exceed the system-imposed limit. - ``ENOMEM``. The available data space is not large enough to accommodate the shared memory segment. .. c:function:: int shmctl(int shmid, int cmd, FAR struct shmid_ds *buf) Provides a variety of shared memory control operations as specified by ``cmd``. The following values for ``cmd`` are available: - ``IPC_STAT``. Place the current value of each member of the ``shmid_ds`` data structure associated with ``shmid`` into the structure pointed to by ``buf``. - ``IPC_SET``. Set the value of the ``shm_perm.mode`` member of the ``shmid_ds`` data structure associated with ``shmid`` to the corresponding value found in the structure pointed to by ``buf``. - ``IPC_RMID``. Remove the shared memory identifier specified by ``shmid`` from the system and destroy the shared memory segment and ``shmid_ds`` data structure associated with it. :param shmid: Shared memory identifier :param cmd: ``shmctl()`` command :param buf: Data associated with the ``shmctl()`` command :return: Upon successful completion, ``shmctl()`` will return 0; otherwise, it will return -1 and set ``errno`` to indicate the error. - ``EACCES``. The argument ``cmd`` is equal to ``IPC_STAT`` and the calling process does not have read permission. - ``EINVAL``. The value of ``shmid`` is not a valid shared memory identifier, or the value of ``cmd``\ is not a valid command. - ``EPERM``. The argument ``cmd`` is equal to ``IPC_RMID`` or ``IPC_SET`` and the effective user ID of the calling process is not equal to that of a process with appropriate privileges and it is not equal to the value of ``shm_perm.cuid`` or ``shm_perm.uid`` in the data structure associated with ``shmid``. - ``EOVERFLOW``. The ``cmd`` argument is ``IPC_STAT`` and the ``gid`` or ``uid`` value is too large to be stored in the structure pointed to by the ``buf`` argument. **POSIX Deviations** - ``IPC_SET``. Does not set the ``shm_perm.uid`` or ``shm_perm.gid``\ members of the ``shmid_ds`` data structure associated with ``shmid`` because user and group IDs are not yet supported by NuttX - ``IPC_SET``. Does not restrict the operation to processes with appropriate privileges or matching user IDs in ``shmid_ds`` data structure associated with ``shmid``. Again because user IDs and user/group privileges are are not yet supported by NuttX - ``IPC_RMID``. Does not restrict the operation to processes with appropriate privileges or matching user IDs in ``shmid_ds`` data structure associated with ``shmid``. Again because user IDs and user/group privileges are are not yet supported by NuttX .. c:function:: int shmdt(FAR const void *shmaddr) Detaches the shared memory segment located at the address specified by ``shmaddr`` from the address space of the calling process. :param shmid: Shared memory identifier :return: Upon successful completion, ``shmdt()`` will decrement the value of ``shm_nattch`` in the data structure associated with the shared memory ID of the attached shared memory segment and return 0. Otherwise, the shared memory segment will not be detached, ``shmdt()`` will return -1, and ``errno`` will be set to indicate the error. - ``EINVAL``. The value of ``shmaddr`` is not the data segment start address of a shared memory segment.