shmctl(2)shmctl(2)NAMEshmctl - Perform shared memory control operations
SYNOPSIS
#include <sys/shm.h>
int shmctl(
int shmid,
int cmd,
struct shmid_ds *buf );
Application developers might want to specify #include statements for
<sys/types.h> and <sys/ipc.h> before the one for <sys/shm.h> if pro‐
grams are being developed for multiple platforms. The additional
#include statements are not required on Tru64 UNIX systems or by ISO or
XSH specifications, but might be required on other vendors' systems
that conform to these standards.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
shmctl(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the ID of the shared memory region. Specifies the type of
command. The possible commands are: IPC_STAT, IPC_SET, IPC_RMID,
SHM_LOCK, and SHM_UNLOCK. Specifies the address of a shmid_ds struc‐
ture.
DESCRIPTION
The shmctl() function provides a variety of shared memory control oper‐
ations as specified by the cmd parameter.
The cmd values and their operations are as follows: Queries the shared
memory region ID by copying the contents of its associated shmid_ds
data structure into the buf structure. Sets the shared memory region
ID by copying values found in the buf structure into corresponding
fields in the shmid_ds structure associated with the shared memory
region ID. The fields are set as follows: The shm_perm.uid field is set
to the owner's user ID. The shm_perm.gid field is set to the owner's
group ID. The shm_perm.mode field is set to the access modes for the
shared memory region. Only the low-order nine bits are set. The
shm_ctime field is set to the time of the last IPC_SET operation.
Removes the shared memory region ID and deallocates its associated
shmid_ds structure. [Tru64 UNIX] Locks the shared memory segment
specified by shmid in memory. [Tru64 UNIX] Unlocks the shared memory
segment specified by shmid in memory.
The shmid_ds structure is used only with the IPC_STAT and IPC_SET com‐
mands. In either case, the calling process must have allocated the
structure before making the call.
[Tru64 UNIX] The SHM_LOCK and SHM_UNLOCK commands can be used to lock
(wire) down a shared segment in memory to prevent it from being paged
out.
NOTES
[Tru64 UNIX] When using the SHM_LOCK command, make sure that the sys‐
tem has enough physical memory available for the shared segment to be
wired without exceeding the system-wide limit or otherwise severely
impacting system performance.
[Tru64 UNIX] The SHM_LOCK operation wires all the pages in a global
shared segment and prevents the pageout daemon from reclaiming any of
the pages. This can potentially lead to thrashing.
The librt library contains alternative interfaces for interprocess com‐
munication. The names of these routines adhere to the format shm_* and
their reference pages are listed in SEE ALSO.
RESTRICTIONS
The following restrictions apply to the shared memory commands: For the
IPC_SET and IPC_RMID commands, the effective user ID of the calling
process must be equal to that of superuser or equal to the value of
shm_perm.cuid or shm_perm.uid in the associated shmid_ds structure.
[Tru64 UNIX] For the SHM_LOCK and SHM_UNLOCK commands, the effective
user ID of the calling process must be equal to that of superuser.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. If the
shmctl() function fails, a value of -1 is returned and errno is set to
indicate the error.
ERRORS
The shmctl() function sets errno to the specified values for the fol‐
lowing conditions: The cmd parameter is IPC_STAT, but the calling
process does not have read permission. [Tru64 UNIX] The cmd parameter
is SHM_LOCK, and the system-wide wire limit has been exceeded. [Tru64
UNIX] The cmd parameter is IPC_STAT or IPC_SET. An error occurred in
accessing the buf structure. The shmid parameter does not specify a
valid shared memory region ID, or cmd is not a valid command.
[Tru64 UNIX] The cmd parameter is SHM_UNLOCK, and the segment
was not locked. The cmd parameter is equal to either IPC_RMID
or IPC_SET, and the calling process does not have appropriate
privilege.
SEE ALSO
Functions: shmat(2), shmdt(2), shmget(2), shm_open(3), shm_unlink(3)
Data structures: shmid_ds(4)
Standards: standards(5)shmctl(2)
