shmctl()-Perform Shared Memory Control Operations



Syntax

#include <sys/shm.h>

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


Threadsafe: Yes

The shmctl() function provides shared memory control operations as specified by cmd on the shared memory segment specified by shmid.

Parameters

shmid
(Input) Shared memory identifier, a positive integer. It is created by the shmget() function and 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.

buf
(I/O) Pointer to the shmid_ds structure to be used to get or set shared memory information.

The cmd parameter can have one of the following values:

'0x0002' or IPC_STAT
Place the current value of each member of the shmid_ds data structure associated with shmid into the structure pointed to by buf. This command requires read permission.
'0x0001' or IPC_SET
Set the value of the following members of the shmid_ds data structure associated with shmid to the corresponding value found in the structure pointed to by buf:

IPC_SET can be performed only by a thread with appropriate privileges or one that has an effective user ID equal to the value of shm_perm.cuid or shm_perm.uid in the shmid_ds data structure associated with shmid.

'0x0000' or IPC_RMID
Remove the shared memory identifier specified by shmid from the system and destroy the shared memory segment and the shmid_ds data structure associated with it. IPC_RMID can be performed only by a thread with appropriate privileges or one that has an effective user ID equal to the value of shm_perm.cuid or shm_perm.uid in the shmid_ds data structure associated with shmid. The structure pointed to by buf is ignored and a NULL pointer is valid.
'0x0006' or SHM_SIZE
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 function is valid for nonteraspace shared memory segments and for teraspace shared memory segments created using the SHM_RESIZE_NP option of shmget(). 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 resizeable teraspace shared memory segment is 268 435 456 bytes (256 MB). SHM_SIZE can be performed only by a thread with appropriate privileges or a thread that has an effective user ID equal to the value of shm_perm.cuid or shm_perm.uid in the shmid_ds data structure associated with shmid.

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

Authorities

Figure 1-15. 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 parameter cmd is equal to IPC_STAT and the calling thread does not have read permission.

[EDAMAGE]
A damaged object was encountered.

The value of shmid corresponds to a shared memory ID that has been marked as 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:

[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.

[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 parameter cmd is equal to IPC_RMID or IPC_SET and both of the following are true:

[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

  1. "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.

Related Information

Example

For an example of using this function, see Using Semaphores and Shared Memory in Appendix A, Examples.

Top | Interprocess Communication APIs | APIs by category

[Information Center Home Page | Feedback ] [Legal | AS/400 Glossary]