shmctl

shmctl

Control a Shared Memory Segment

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
USAGE NOTES
EXAMPLE 1
EXAMPLE 2
RELATED FUNCTIONS

SYNOPSIS

#include <sys/shm.h>
int shmctl(int id, int cmd,
           struct shmid_ds *buf);

DESCRIPTION

The shmctl function is used to perform one of several control operations on a shared memory segment.

Note: See the shmget function description in section shmget for general information about shared memory segments. [cautionend]
The id argument to shmctl specifies a shared memory segment id. This argument is an id, such as the id returned by shmget , not a memory segment key, which might be passed as an argument to shmget .

The cmd argument should be specified as a symbolic constant specifying the specific operation to be performed by shmctl . The constant values are described below.

Several of the shmctl operations allow you to obtain or access the shared memory id data structure, which is mapped by the struct shmid_ds type defined in sys/shm.h .

This data structure is defined as follows:

struct shmid_ds {
   /* permission information */
   struct ipc_perm shm_perm;

   /* segment size */
   int shm_segsz;

   /* process id for last shm operation */
   pid_t shm_lpid;

   /* process id of creator */
   pid_t shm_cpid;

   /* number of times segment attached */
   unsigned shm_nattch;

   /* time of last shmat call */
   time_t shm_atime;

   /* time of last shmdt call */
   time_t shm_dtime;

   /* time of last change by shmget/shmctl */
   time_t shm_ctime;
};

The ipc_perm structure contains security information about the owner and the creator of the memory segment and is defined as follows:

struct ipc_perm {
   /* owner's effective user ID */
   uid_t uid;

   /* owner's effective group ID */
   gid_t gid;

   /* creator's effective user ID */
   uid_t cuid;

   /* creator's effective group ID */
   gid_t cgid;

   /* read/write permission bits */
   mode_t mode;
};

For shmctl operations which access or modify the shared memory id data structure, the buf argument addresses a struct shmid_ds , used as described below. For other operations, the buf argument is ignored.

The cmd values accepted by shmctl and their meanings are as follows:

IPC_RMID - Removes the shared memory segment and its id from the system, after all users have detached it. The buf argument is not used by this operation.
IPC_SET - Can be used to change the ownership of a shared memory segment or the access rules. The contents of buf->shm_perm.uid , buf->shm_perm.gid and buf->shm_perm.mode will be copied to the shared memory id data structure.
IPC_STAT - Returns the contents of the shared memory id data structure. All elements of the data structure are stored in the object addressed by buf .

RETURN VALUE

shmctl returns 0 if successful, or -1 if unsuccessful.

USAGE NOTES

The shmctl function can only be used with MVS 5.2.2 or a later release.

EXAMPLE 1

Refer to shmat for an example that uses the functions shmat() , shmctl() , shmdt() , and shmget() to establish an IPC Client using a Shared Memory Segment.

EXAMPLE 2

Refer to shmat for an example that uses the functions shmat() , shmctl() , shmdt() , and shmget() to establish an IPC Server using a Shared Memory Segment.

RELATED FUNCTIONS

shmat , shmdt , shmget

Chapter Contents
Previous
Next
Top of Page