OSF

NAME

shmctl −  Performs shared memory control operations

SYNOPSIS

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
int shmctl(
int shmid,
int cmd,
struct shmid_ds ∗buf);

PARAMETERS

shmidSpecifies the ID of the shared memory region. 

cmdSpecifies the type of command.  The possible commands and the operations they perform are as follows:

IPC_STATQueries the shared memory region ID by copying the contents of its associated shmid_ds data structure into the buf structure. 

IPC_SETSets 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.  This is a restricted operation.  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. 

IPC_RMIDRemoves the shared memory region ID and deallocates its associated shmid_ds structure.  This is a restricted operation.  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. 

bufSpecifies the address of a shmid_ds structure.  This structure is used only with the IPC_STAT and IPC_SET commands.  With IPC_STAT, the results of the query are copied to this structure.  With IPC_SET, the values in this structure are used to set the corresponding fields in the shmid_ds structure associated with the shared memory region ID.  In either case, the calling process must have allocated the structure before making the call. 

DESCRIPTION

The shmctl() function allows a process to query or set the contents of the shmid_ds structure associated with the specified shared memory region ID.  It also allows a process to remove the shared memory region’s ID and its associated shmid_ds structure.  The cmd value determines which operation is performed. 

The IPC_SET command uses the user-supplied contents of the buf structure to set 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. 

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

If the shmctl() function fails, errno may be set to one or more of the following values:

[EINVAL]The shmid parameter does not specify a valid shared memory region ID, or cmd is not a valid command. 

[EACCES]The cmd parameter is IPC_STAT, but the calling process does not have read permission. 

[EPERM]The cmd parameter is equal to either IPC_RMID or IPC_SET, and the calling process does not have appropriate privilege. 

[EFAULT]The cmd parameter is IPC_STAT or IPC_SET.  An error occurred in accessing the buf structure. 

RELATED INFORMATION

Functions: shmat(2), shmdt(2), shmget(2)

Data structures: shmid_ds(4)