shmctl - Perform shared memory control operations
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 programs 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.
Interfaces documented on this reference page conform to
industry standards 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.
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 structure.
The shmctl() function provides a variety of shared memory
control operations 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 commands. 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.
[Tru64 UNIX] When using the SHM_LOCK command, make sure
that the system 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 communication. The names of these routines
adhere to the format shm_* and their reference pages are
listed in SEE ALSO.
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.
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.
The shmctl() function sets errno to the specified values
for the following 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.
Functions: shmat(2), shmdt(2), shmget(2), shm_open(3),
Data structures: shmid_ds(4)
[ Back ]