[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2
shmctl Subroutine
Purpose
Controls shared memory operations.
Library
Standard C Library (libc.a)
Syntax
#include <sys/shm.h>
int shmctl (SharedMemoryID, Command, Buffer)
int SharedMemoryID, Command;
struct shmid_ds *Buffer;
Description
The shmctl subroutine performs a variety of shared-memory
control operations as specified by the Command parameter.
The following limits apply to shared memory:
- Maximum shared-memory segment size is 2G
bytes.
- Minimum shared-memory segment size is 1 byte.
- Maximum number of shared memory IDs is 4096.
Parameters
SharedMemoryID |
Specifies an identifier returned by the shmget subroutine. |
Buffer |
Indicates a pointer to the shmid_ds structure. The shmid_ds structure is defined in
the sys/shm.h file. |
Command |
The following commands are available:
IPC_STAT |
Obtains status information about the shared memory segment identified by the SharedMemoryID
parameter. This information is stored in the area pointed to by the Buffer parameter. The calling
process must have read permission to run this command. |
IPC_ SET |
Sets the user and group IDs of the owner as well as the access permissions for the shared
memory segment identified by the SharedMemoryID parameter. This command sets the following
fields:
shm_perm.uid /* owning user ID */
shm_perm.gid /* owning group ID */
shm_perm.mode /* permission bits only */
You must have an effective user ID equal to root or to the value of the shm_perm.cuid
or
shm_perm.uid
field in the shmid_ds data structure identified by the
SharedMemoryID parameter. |
IPC_RMID |
Removes the shared memory identifier specified by the SharedMemoryID parameter from
the system and erases the shared memory segment and data structure associated with it. This command is
only executed by a process that has an effective user ID equal either to that of a process with the
appropriate privileges or to the value of the shm_perm.uid
or shm_perm.cuid
field in the data structure identified by the SharedMemoryID parameter. |
SHM_SIZE |
Sets the size of the shared memory segment to the value specified by the shm_segsz
field of the structure specified by the Buffer parameter. This value can be larger or smaller
than the current size. The limit is the maximum shared-memory segment size. This command is only
executed by a process that has an effective user ID equal either to that of a process with the
appropriate privileges or to the value of the shm_perm.uid
or shm_perm.cuid
field in the data structure identified by the SharedMemoryID parameter. This command is not supported for regions created with the environment variable EXTSHM=ON. This results in a return value of -1 with
errno set to EINVAL. Attempting to use the SHM_SIZE on a shared memory region larger than 256MB or
attempting to increase the size of a shared memory region larger than 256MB results in a return value of
-1 with errno set to EINVAL. |
|
Return Values
When completed successfully, the shmctl subroutine returns a value of 0. Otherwise, it returns a value of -1 and the errno global variable is set to
indicate the error.
Error Codes
The shmctl subroutine is unsuccessful if one or more of the following are true:
EACCES |
The Command parameter is equal to the IPC_STAT value and read permission is
denied to the calling process. |
EFAULT |
The Buffer parameter points to a location outside the allocated address space of the
process. |
EINVAL |
The SharedMemoryID parameter is not a valid shared memory identifier. |
EINVAL |
The Command parameter is not a valid command. |
EINVAL |
The Command parameter is equal to the SHM_SIZE value and the value of the
shm_segsz
field of the structure specified by the Buffer parameter is not
valid. |
EINVAL |
The Command parameter is equal to the SHM_SIZE value and the shared memory region
was created with the environment variable
EXTSHM=ON. |
ENOMEM |
The Command parameter is equal to the SHM_SIZE value, and the attempt to change
the segment size is unsuccessful because the system does not have enough memory. |
EPERM |
The Command parameter is equal to the IPC_RMID or SHM_SIZE value, and
the effective user ID of the calling process is not equal to the value of the shm_perm.uid
or shm_perm.cuid
field in the data structure identified by the SharedMemoryID parameter. The effective user ID of the calling process is not the root user ID. |
Implementation Specifics
This subroutine is part of Base Operating System (BOS) Runtime.
Related Information
The disclaim subroutine, shmat subroutine, shmdt
subroutine, shmget subroutine.
List of Memory Manipulation
Services, Subroutines Overview, Understanding Memory
Mapping in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]