shmctl()--Perform Shared Memory Control Operations

Syntax

 #include <sys/shm.h>

 int shmctl(int shmid, int cmd, struct shmid_ds *buf);

  Service Program Name: QP0ZUSHR

  Default Public Authority: *USE

  Threadsafe: Yes

The shmctl() function allows the caller to control the shared memory segment specified by the shmid parameter.

A shared memory segment is controlled by setting the cmd parameter to one of the following values:

IPC_RMID (0x00000000)

Remove the shared memory segment identifier shmid from the system and destroy the shared memory segment.

The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment. The structure pointed to by *buf is ignored and can be NULL.

IPC_SET (0x00000001)

Set the user ID of the owner, the group ID of the owner, and the permissions for the shared memory segment to the values in the shm_perm.uid, shm_perm.gid, and shm_perm.mode members of the shmid_ds data structure pointed to by *buf.

The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.

IPC_STAT (0x00000002)

Store the current value of each member of the shmid_ds data structure into the structure pointed to by *buf. The IPC_STAT command requires read permission to the shared memory segment.

SHM_SIZE (0x00000006)

Set the size of the shared memory segment using the shm_segsz member of the shmid_ds data structure pointed to by *buf. This value may be larger or smaller than the current size. This command is valid for nonteraspace shared memory segments and for teraspace shared memory segments created using the SHM_RESIZE_NP option on the shmget() or shmget64() function. The maximum size to which a nonteraspace shared memory segment may be expanded is 16 773 120 bytes (16 MB minus 4096 bytes). The maximum size of a resizable teraspace shared memory segment is 268 435 456 bytes (256 MB).

The SHM_SIZE command can be run only by a thread with appropriate privileges or a thread that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.

If a shared memory segment is resized to a smaller size, other threads using the memory that is being removed from the shared memory segment may experience memory exceptions when accessing that memory.

Parameters

shmid: (Input) Shared memory identifier, a positive integer. It is returned by the shmget() or shmget64() function and is used to identify the shared memory segment on which to perform the control operation.
cmd: (Input) Command, the control operation to perform on the shared memory segment. Valid values are listed above.
buf: (I/O) Bufer, the pointer to the shmid_ds structure to be used to get or set shared memory information.
The members of the shmid_ds structure are as follows:

struct ipc_perm shm_perm

The members of the ipc_perm structure are as follows:

uid_t uid	The user ID of the owner of the segment.
gid_t gid	The group ID of the owner of the segment.
uid_t cuid	The user ID of the creator of the segment.
gid_t cgid	The group ID of the creator of the segment.
mode_t mode	The permissions for the segment.

size_t shm_segsz

The size of the segment in bytes.

pid_t shm_lpid

The process ID of the last job to attach to or detach from the segment using shmat() or shmdt().

pid_t shm_cpid

The process ID of the job that created the segment using shmget() or shmget64().

int shm_nattch

The number of jobs attached to the segment.

time_t shm_atime

The time the last job attached to the segment using shmat().

time_t shm_dtime

The time the last job detached from the segment using shmdt().

time_t shm_ctime

The time the last job changed the segment using shmctl() or shmctl64().

Authorities

Authorization Required for shmctl()

Object Referred to	Authority Required	errno
Shared memory segment for which state information is retrieved (cmd = IPC_STAT)	Read	EACCES
Shared memory segment for which state information is set (cmd = IPC_SET)	See Note	EPERM
Shared memory segment to be removed (cmd = IPC_RMID)	See Note	EPERM
Shared memory segment to be resized (cmd = SHM_SIZE)	See Note	EPERM

Note: To set shared memory segment information, to remove a shared memory segment, or to resize a shared memory segment, the thread must be the owner or creator of the shared memory segment or have appropriate privileges.

Return Value

0	shmctl() was successful.
-1	shmctl() was not successful. The errno variable is set to indicate the error.

Error Conditions

If shmctl() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

The cmd parameter is IPC_STAT and the calling thread does not have read permission to shared memory segment.

[EDAMAGE]

A damaged object was encountered.

The shared memory segment has been damaged by a previous shared memory operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

The shmid parameter is not a valid shared memory identifier.
The cmd parameter is not a valid command.
The cmd parameter is SHM_SIZE, and the teraspace shared memory segment cannot be resized because it was not created by specifying SHM_RESIZE_NP on the shmflg parameter of shmget() or shmget64().
The cmd parameter is SHM_SIZE, and the new size is not valid for the shared memory segment.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

A shared memory identifier segment is to be resized, but the amount of available physical memory is not sufficient to fulfill the request.

[EOVERFLOW]

Object is too large to process.

The object's data size exceeds the limit allowed by this function.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

The cmd parameter is IPC_RMID, IPC_SET, or SHM_SIZE and both of the following are true:

the calling thread does not have the appropriate privileges.
the effective user ID of the calling thread is not equal to the user ID of the owner or the user ID of the creator of the shared memory segment.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

"Appropriate privileges" is defined to be *ALLOBJ special authority. If the user profile under which the thread is running does not have *ALLOBJ special authority, the thread does not have appropriate privileges.
If the IPC_STAT command is being performed, the shmctl() function will fail with the [EOVERFLOW] error when the shared memory segment size in bytes cannot be represented correctly in the structure pointed to by *buf (i.e. the size is larger than 4 294 967 295 bytes (4GB minus 1 byte)). To perform the IPC_STAT command on a shared memory segment larger than 4 294 967 295 bytes use the shmclt64() function.
To set the page size of the storage backing a teraspace shared memory segment, use the shmctl64() function.

Related Information

The <sys/shm.h> file (see Header Files for UNIX^®-Type Functions)
shmat()--Attach Shared Memory Segment to Current Process
shmctl64()--Perform Shared Memory Control Operations (64-Bit Enabled)
shmdt()--Detach Shared Memory Segment from Calling Process
shmget()--Get ID of Shared Memory Segment with Key
shmget64()--Get ID of Shared Memory Segment with Key (64-Bit Enabled)

Example

For an example of using this function, see Example: Using semaphore set and shared memory functions.

API introduced: V3R6

[ Back to top | UNIX-Type APIs | APIs by category ]