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.