dshm_control(3dshm)

dshm_control -- dynamically mapped shared memory control operations

Synopsis

   #include <dshm.h>
   
   int dshm_control(int dshmid, int cmd, ... /* struct dshmid_ds *buf */);

Description

dshm_control provides a variety of dynamically mapped shared memory control operations as specified by cmd. The following cmds are available:

IPC_STAT: Returns information about the segment in the following members of the structure pointed to by buf.

struct ipc_perm dshm_perm operation permission structure

pid_t dshm_lpid pid of the last dshm_attach or dshm_detach caller

pid_t dshm_cpid pid of the creator

unsigned long dshm_nattach number of current attaches

time_t dshm_atime time of last dshm_attach call

time_t dshm_dtime time of last dshm_detach call

time_t dshm_ctime time of last change by dshm_control

const void* dshm_mapaddr starting logical address for map

size_t dshm_mapsize map size in bytes

size_t dshm_bufsize individual buffer size in bytes

unsigned long dshm_abufcnt number of application buffers in object (specified by buffer_count at dshm_get creation time)

unsigned long dshm_tbufcnt total number of buffers in object (dshm_abufcnt plus library administrative overhead)

struct ipc_perm	dshm_perm	operation permission structure
pid_t	dshm_lpid	pid of the last dshm_attach or dshm_detach caller
pid_t	dshm_cpid	pid of the creator
unsigned long	dshm_nattach	number of current attaches
time_t	dshm_atime	time of last dshm_attach call
time_t	dshm_dtime	time of last dshm_detach call
time_t	dshm_ctime	time of last change by dshm_control
const void*	dshm_mapaddr	starting logical address for map
size_t	dshm_mapsize	map size in bytes
size_t	dshm_bufsize	individual buffer size in bytes
unsigned long	dshm_abufcnt	number of application buffers in object (specified by buffer_count at dshm_get creation time)
unsigned long	dshm_tbufcnt	total number of buffers in object (dshm_abufcnt plus library administrative overhead)

IPC_SET

Set the value of the following members of the data structure associated with dshmid to the corresponding value found in the structure pointed to by buf:

   dshm_perm.uid
   dshm_perm.gid
   dshm_perm.mode /* only access permission bits */

This command can be executed only by a process that has an effective user id equal to the value of dshm_perm.cuid or dshm_perm.uid in the data structure associated with dshmid, or by a process that has the P_OWNER privilege.

IPC_RMID

Remove the dynamically mapped shared memory identifier specified by dshmid from the system and destroy the dynamically mapped shared memory segment and data structure associated with it. This command can be executed only by a process that has an effective user id equal to the value of dshm_perm.cuid or dshm_perm.uid in the data structure associated with dshmid, or by a process that has the P_OWNER privilege.

Return values

On success, dshm_control returns 0.

On failure, dshm_control returns -1 and sets errno to identify the error.

Errors

In the following conditions, dshm_control fails and sets errno to:

EACCES: cmd is equal to IPC_STAT and {READ} operation permission is denied to the calling process.
EINVAL: dshmid is not a valid shared memory identifier.
EINVAL: cmd is not a valid command.
EINVAL: cmd is IPC_SET and dshm_perm.uid or dshm_perm.gid is not valid.
EINVAL: cmd is DSHM_SETPLACE and one or more of the values in dshmid_ds is incorrect.
EOVERFLOW: cmd is IPC_STAT and uid or gid is too large to be stored in the structure pointed to by buf.
EPERM: cmd is equal to IPC_RMID or IPC_SET and the effective user is not equal to the value of dshm_perm.cuid or shm_perm.uid in the data structure associated with dshmid and the process does not have the P_OWNER privilege.
EPERM: cmd is equal to DSHM_SETPLACE and the effective user is not equal to the value of dshm_perm.cuid or dshm_perm.uid in the data structure associated with dshmid and the process does not have the P_OWNER privilege.
EAGAIN: cmd is DSHM_SETPLACE and the call failed due to resource constraints within the kernel.
ENOTSUP: cmd is DSHM_SETPLACE and the system does not support the requested placement style.
EFAULT: buf points to an illegal address.

Usage

The user must explicitly remove dynamically mapped shared memory segments after the last reference to them has been removed.

References

dshm_alignment(3dshm), dshm_attach(3dshm), dshm_bufindex(3dshm), dshm_detach(3dshm), dshm_get(3dshm), dshm_map(3dshm), dshm_minmapsize(3dshm), dshm_reattach(3dshm), dshm_unmap(3dshm), dshm_updatetlb(3dshm)