.TH shmctl() "" "" "General Function (libc)"
.PC "Manipulate shared memory"
.B "#include <sys/types.h>"
.B "#include <sys/ipc.h>"
.B "#include <sys/shm.h>"
\fBshmctl(\fIshmid\^\fB, \fIcommand\^\fB, \fIbuf\^\fB)\fR
\fBint \fIshmid\^\fB, \fIcommand\^\fB; struct shmid_ds *\fIbuf\^\fB;\fR
.PP
.II "interprocess communication^shared memory"
.II "shared memory^shmctl()"
.B shmctl()
controls the \*(CO system's shared-memory facility.
Note that shared memory consists of the segment of memory being shared,
plus a copy of structure
.BR shmid_ds ,
which is defined in header file
.BR <sys/shm.h> .
This structure describes the shared-memory segment and identifies
who can manipulate it, and how.
.PP
.I command
names the operation that you want
.B shmctl()
to perform, as follows:
.IP \fBIPC_RMID\fR 1.0i
Remove the system identifier
.I shmid
and destroy its associated shared memory segment and
.B shmid_ds
structure.
Only the superuser
.B root
or the user whose effective user ID matches the value of field
.B uid
can invoke this command.
.IP \fBIPC_SET\fR
Copy fields
.BR shm_perm.uid ,
.BR shm_perm.gid ,
and
.B shm_perm.mode
(low nine bits only) from the
.B ipc_perm
associated with
.I buf
into
.IR shmid .
Only the superuser
.B root
or the user who created this shared-memory segment
can invoke this command.
.IP \fBIPC_STAT\fR
Copy every element of the
.B shmid_ds
associated with
.I shmid
into the one pointed to by
.IR buf .
.IP \fBSHM_LOCK\fR
Lock the shared-memory segment
.IR shmid ,
to keep it from being paged out of memory.
Only the superuser
.B root
can invoke this command.
Because \*(CO does not support paging, this command present does nothing.
.IP \fBSHM_UNLOCK\fR
Unlock the shared-memory segment
.IR shmid ,
to permit it to be paged out of memory.
Only the superuser
.B root
can invoke this command.
Because \*(CO does not support paging, this command present does nothing.
.PP
.B shmctl()
fails if any of the following is true:
.IP \(bu 0.3i
.I shmid
is not a valid shared-memory identifier.
.B shmget()
sets
.B errno
to \fBEINVAL\fR.
.IP \(bu
.I command
is not a valid command (\fBEINVAL\fR).
.IP \(bu
.I command
equals
.B IPC_STAT
but the owner of the calling process lacks permission
(\fBEACCES\fR).
.IP \(bu
.I command
equals
.B IPC_RMID
or
.B IPC_SET
but the owner of the calling process lacks permission (\fBEPERM\fR).
.IP \(bu
.I buf
points to an illegal address (\fBEFAULT\fR).
.PP
.B shmctl()
returns zero if all went well; otherwise, it returns \-1 and sets
.B errno
to an appropriate value.
.SH Example
For an example of this function, see the Lexicon entry for
.BR shmget() .
.SH Files
.B
/usr/include/sys/ipc.h
.br
/usr/include/sys/shm.h
.R
.SH "See Also"
.Xr "libc," libc
.Xr "shmat()," shmat
.Xr "shmdt()," shmdt
.Xr "shmget()" shmget
.SH Notes
For information on other methods of interprocess communication, see the
Lexicon entries for
.B semctl()
and
.BR msgctl() .
