[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, 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:
- 256M bytes before AIX 4.3.1
- 2G bytes for AIX 4.3.1 through AIX 5.1
- 64G bytes for 64-bit applications for AIX 5.1 and later
- Minimum shared-memory segment size is 1 byte.
- Maximum number of shared memory IDs is 4096 for operating system releases
before AIX 4.3.2 and 131072 for AIX 4.3.2 and following.
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 superuser 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. |
EOVERFLOW |
The Command parameter is IPC_STAT and the size of the shared memory region is greater
than or equal to 4G bytes. This only happens with 32-bit programs. |
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. |
Related Information
The disclaim subroutine, shmat
subroutine, shmdt subroutine, shmget subroutine.
The ipcs command and ipcrm command.
List of Memory Manipulation
Services, Subroutines Overview, Understanding Memory Mapping in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]