NAME
shmctl() — shared memory control operations
SYNOPSIS
#include <sys/shm.h>
int shmctl(int shmid, int cmd, struct shmid_ds *buf);
DESCRIPTION
The
shmctl()
system call provides a variety of shared memory control operations
as specified by the
cmd
argument.
cmd
can have the following values:
- IPC_STAT
Place the current value of each member of the data structure associated with
shmid
into the structure pointed to by
buf.
The contents of this structure are defined in
glossary(9).
- IPC_SET
Set the value of the following members of the data structure associated with
shmid
to the corresponding value found in the structure pointed to by
buf:
shm_perm.uid
shm_perm.gid
shm_perm.mode /* only low 9 bits */
This
cmd
can only be executed by a process that has an effective user ID
equal to either that of a user
having appropriate privileges
or to the value of either
shm_perm.uid
or
shm_perm.cuid
in the data structure associated with
shmid.
This
cmd
cannot be executed on a shared memory segment that has been created with
relaxed isolation.
- IPC_RMID
Remove the shared memory identifier specified by
shmid
from the system and destroy the shared memory segment
and data structure associated with it.
If the segment is attached to one or more processes,
then the segment key is changed to
IPC_PRIVATE
and the segment is marked removed.
The segment disappears when the last attached process detaches it.
This
cmd
can only be executed by a process that has an effective user ID
equal to either that of a user with
appropriate privileges
or to the value of either
shm_perm.uid
or
shm_perm.cuid
in the data structure associated with
shmid.
- SHM_LOCK
Lock the shared memory segment specified by
shmid
in memory.
This
cmd
can only be executed by a process that either has an effective user ID
equal to that of a user
having appropriate privileges
or has an effective user ID equal to the value of either
shm_perm.uid
or
shm_perm.cuid
in the data structure associated with
shmid
and has the
PRIV_MLOCK
privilege (see
getprivgrp(2)).
- SHM_UNLOCK
Unlock the shared memory segment specified by
shmid.
This
cmd
can only be executed by a process that either has an effective user ID
equal to a user
having appropriate privileges
or has an effective user ID equal to the value of either
shm_perm.uid
or
shm_perm.cuid
in the data structure associated with
shmid
and has the
PRIV_MLOCK
privilege (see
getprivgrp(2)).
RETURN VALUE
shmctl()
returns the following values:
- 0
Successful completion.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If
shmctl()
fails,
errno
is set to one of the following values.
- EACCES
cmd
is equal to
IPC_STAT
and Read operation permission is denied to the calling process (see
shared memory operation permissions
in
glossary(9)).
- EFAULT
buf
points to an illegal address.
The reliable detection of this error is implementation dependent.
- EINVAL
cmd
is equal to
SHM_UNLOCK
and the shared-memory segment specified by
shmid
is not locked in memory.
- EINVAL
shmid
is not a valid shared memory identifier.
- EINVAL
cmd
is not a valid command, or the command contains invalid parameters.
- ENOMEM
cmd
is equal to
SHM_LOCK
and there is not sufficient lockable memory to fill the request.
- EOVERFLOW
cmd
is equal to
IPC_STAT.
The attached process count of a shared memory object is too large
for the field in the data structure provided by the application.
Recompile the application with the latest
/usr/include/sys/ipc.h
file to resolve this issue.
- EPERM
cmd
is equal to
IPC_RMID,
IPC_SET,
SHM_LOCK,
or
SHM_UNLOCK
and the effective user ID of the calling process
is not equal to that of a user
having appropriate privileges
and it is not equal to the value of either
shm_perm.uid
or
shm_perm.cuid
in the data structure associated with
shmid.
cmd
is equal to
IPC_SET
and the shared memory segment has
relaxed isolation.
- EPERM
cmd
is equal to
SHM_LOCK
or
SHM_UNLOCK
and the effective user ID of the calling process
is not equal to that of a user
having appropriate privileges
and the calling process does not have the
PRIV_MLOCK
privilege (see
getprivgrp(2)).
EXAMPLES
The following call to
shmctl()
locks in memory the shared memory segment represented by
myshmid.
This example assumes the process has a valid shmid,
which can be obtained by calling
shmget(2).
shmctl (myshmid, SHM_LOCK, 0);
The following call to
shmctl()
removes the shared memory segment represented by
myshmid.
This example assumes the process has a valid
shmid,
which can be obtained by calling
shmget()
(see
shmget(2).
shmctl (myshmid, IPC_RMID, 0);
AUTHOR
shmctl()
was developed by
AT&T and HP.
STANDARDS CONFORMANCE
shmctl(): SVID2, SVID3, XPG2, XPG3, XPG4