*** UNIX MANUAL PAGE BROWSER ***

shmctl(2) System Calls Manual shmctl(2) NAME shmctl - Performs shared memory control operations SYNOPSIS #include <sys/shm.h> int shmctl( int shmid, int cmd struct shmid_ds *buf); Application developers may want to specify #include statements for <sys/types.h> and <sys/ipc.h> before the one for <sys/shm.h> if pro- grams are being developed for multiple platforms. The additional #in- clude statements are not required on DIGITAL UNIX systems or by ISO or X/Open standards, but may be required on other vendors' systems that conform to these standards. STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: shmctl(): XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies the ID of the shared memory region. Specifies the type of command. The possible commands are: IPC_STAT, IPC_SET, IPC_RMID, SHM_LOCK, and SHM_UNLOCK. Specifies the address of a shmid_ds struc- ture. DESCRIPTION The shmctl() function provides a variety of shared memory control oper- ations as specified by the cmd parameter. The cmd values and their operations are as follows: Queries the shared memory region ID by copying the contents of its associated shmid_ds data structure into the buf structure. Sets 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 re- gion 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. Removes the shared memory region ID and deallocates its associated shmid_ds structure. [Digital] Locks the shared memory segment specified by shmid in memory. [Digital] Unlocks the shared memory segment speci- fied by shmid in memory. The shmid_ds structure is used only with the IPC_STAT and IPC_SET com- mands. In either case, the calling process must have allocated the structure before making the call. [Digital] The SHM_LOCK and SHM_UNLOCK commands can be used to lock (wire) down a shared segment in memory to prevent it from being paged out. NOTES [Digital] When using the SHM_LOCK command, make sure that the system has enough physical memory available for the shared segment to be wired without exceeding the system-wide limit or otherwise severely impacting system performance. [Digital] The SHM_LOCK operation wires all the pages in a global shared segment and prevents the pageout daemon from reclaiming any of the pages. This can potentially lead to thrashing. RESTRICTIONS The following restrictions apply to the shared memory commands: For the IPC_SET and IPC_RMID commands, 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. [Digital] For the SHM_LOCK and SHM_UNLOCK commands, the effective user ID of the calling process must be equal to that of superuser. 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 The shmctl() function sets errno to the specified values for the fol- lowing conditions: The cmd parameter is IPC_STAT, but the calling process does not have read permission. [Digital] The cmd parameter is SHM_LOCK, and the system-wide wire limit has been exceeded. [Digi- tal] The cmd parameter is IPC_STAT or IPC_SET. An error occurred in accessing the buf structure. The shmid parameter does not specify a valid shared memory region ID, or cmd is not a valid command. [Digital] The cmd parameter is SHM_UNLOCK, and the segment was not locked. The cmd parameter is equal to either IPC_RMID or IPC_SET, and the calling process does not have appropriate priv- ilege. RELATED INFORMATION Functions: shmat(2), shmdt(2), shmget(2) Data structures: shmid_ds(4) Standards: standards(5) delim off shmctl(2)