Controls shared memory operations.
Standard C Library (libc.a)
#include <sys/shm.h>
int shmctl (SharedMemoryID, Command, Buffer)
int SharedMemoryID, Command;
struct shmid_ds * Buffer;
The shmctl subroutine performs a variety of shared-memory control operations as specified by the Command parameter.
The following limits apply to shared memory:
| Item | Description |
|---|---|
| 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:
|
|
|
|
|
| Command continued | The following commands are available:
|
|
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.
The shmctl subroutine is unsuccessful if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | The Command parameter is equal to the IPC_STAT or SHM_GETLBA 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, SHM_PAGESIZE, SHM_LOCK or SHM_BSR value and the shared memory region was created with the environment variable EXTSHM=ON. |
| EINVAL | The Command parameter is equal to the SHM_PAGESIZE value and the value of the shm_pagesize field of the structure specified by the Buffer parameter is not supported. |
| EINVAL | The Command parameter is equal to SHM_UNLOCK, and the specified shared memory segment was not previously locked by a SHM_LOCK operation. |
| EINVAL | The Command parameter is equal to SHM_LOCK SHM_UNLOCK, or SHM_BSR and the Buffer parameter is not NULL. |
| EINVAL | The Command parameter is equal to SHM_BSR, and the shared memory region’s page size has previously been changed via the SHM_PAGESIZE command. |
| ENOMEM | The Command parameter is SHM_BSR, and there is insufficient BSR memory available to back the entire shared memory segment. |
| 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. |
| ENOMEM | The Command parameter is SHM_LOCK, and locking the pages in the specified shared memory segment would exceed the limit on the amount of memory the calling process may lock. |
| ENOMEM | The Command parameter is SHM_PAGESIZE, and there are insufficient pages of the specified page size to back the entire shared memory segment. |
| 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 IPC_RMID, SHM_SIZE, SHM_PAGESIZE, SHM_LOCK, or SHM_UNLOCK, 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. |
| EPERM | The Command parameter is SHM_PAGESIZE, and the calling process does not have the appropriate privilege to allocate pages of the specified page size. |
| EPERM | The Command parameter is SHM_LOCK SHM_UNLOCK, or SHM_BSR and the calling process does not have the appropriate privilege to perform the requested operation. |
| EBUSY | The Command parameter is SHM_LOCK or SHM_UNLOCK, and the specified shared memory segment is currently being used for I/O or is attached by one or more processes. |
| EBUSY | The Command parameter is SHM_PAGESIZE or SHM_BSR and the specified shared memory segment has already been attached by one or more processes or has been pinned via SHM_PIN or SHM_LOCK. |
The following example allocates a 32MB shared memory region, changes the page size for the shared memory region to 64K, and then pins all of the pages in the shared memory region:
int id;
size_t shm_size;
struct shmid_ds shm_buf = { 0 };
psize_t psize_64k;
psize_64k = 64 * 1024;
/* Create a 32MB shared memory region */
shm_size = 32*1024*1024;
/* Allocate the shared memory region */
if ((id = shmget(IPC_PRIVATE, shm_size, IPC_CREAT)) < 0)
{
perror("shmget() failed");
return -1;
}
/* Use 64K pages for the shared memory region */
shm_buf.shm_pagesize = psize_64k;
if (shmctl(id, SHM_PAGESIZE, &shm_buf))
{
perror("shmctl(SHM_PAGESIZE) failed");
}
/* Pin all of the pages in the shared memory region */
if (shmctl(id, SHM_LOCK, NULL))
{
perror("shmctl(SHM_LOCK) failed");
}The following example allocates a 16MB shared memory region and determines the minimum alignment of the address at which an application can shmat() the shared memory region:
int id;
size_t shm_size;
struct shmid_ds shm_buf = { 0 };
/* Create a 16MB shared memory region */
shm_size = 16*1024*1024;
/* Allocate the shared memory region */
if ((id = shmget(IPC_PRIVATE, shm_size, IPC_CREAT)) < 0)
{
perror("shmget() failed");
return -1;
}
/* Determine the address alignment requirements */
if (shmctl(id, SHM_GETLBA, &shm_buf))
{
perror("shmctl(SHM_GETLBA) failed");
}
else
{
printf("shmlba = %08llx\n", shm_buf.shm_lba);
}