shmctl(2) DG/UX R4.11MU05 shmctl(2)
NAME
shmctl - shared memory control operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
int shmctl (shmid, cmd, buf)
int shmid;
int cmd;
struct shmidds * buf;
where:
shmid The shared memory identifier of the shared area to be
operated on
cmd The specific shared memory operation (IPC_STAT, IPC_SET, or
IPC_RMID)
buf The address of a shared memory structure to be used in the
operation (used only if command is IPC_STAT or IPC_SET)
DESCRIPTION
The shmctl system call obtains or modifies information on shared
memory segments previously defined by shmget. The shmctl call also
allows for the destruction of shared memory segments. The action
performed by shmctl is determined by the value of the cmd parameter
as follows:
IPC_STAT Get status information. Returns the current value of each
member of the shared memory data structure (shmidds)
associated with the shared memory segment specified by
shmid into the buffer pointed to by buf. This command does
not change the values of any of the fields in the shared
memory data structure. If an error occurs, the contents of
the buffer pointed to by buf are undefined.
IPC_SET Set status information. Set the current value of each
member of the shared memory data structure (shmidds)
associated with the shared memory segment specified by
shmid to the corresponding value in the buffer pointed to
by buf. Only the following fields may be set:
shmperm.uid
shmperm.gid
shmperm.mode
In addition to setting the above fields, this command
causes the shmctime field to be set to the current time.
If an error occurs, no changes are made to any of the
fields in the shared memory descriptor.
IPC_RMID Remove shared memory identifier. This "deletes" the shared
memory identifier specified by shmid from the system. This
command has "delete on last detach" semantics. The shared
area segment is not actually destroyed until all processes
that currently have the area attached detach from it via
the shmdt operation. However, no other processes may
attach to the shared area via the shmat call. (Note,
however, that implicit attach operations that occur as part
of a fork operation may still occur; see shmat.) Once this
command is performed on a shmid, the only operations that
may be performed on that shmid are the IPC_STAT command of
shmctl and the shmdt operation. All other operations act
as though shmid is invalid; that is, return the EINVAL
status code. A shared segment that has had this operation
performed on it will have the SHM_DEST bit set in the
shmperm.mode field of its shared memory data structure.
(This information is returned by the IPC_STAT command of
shmctl.) This command updates the shmctime field in the
shared segment's data structure to the current time. If an
error occurs, the shared segment is not deleted and no
changes are made to its shared memory data structure.
Note that the shmidds struct that is returned with the IPC_STAT and
IPC_SET action arguments differs in the ELF and COFF environments.
Specifically, the fields shmnattch, shmcnattch are type unsigned
long in the ELF environment and type unsigned short in the COFF
environment. In both environments, a shared memory object allows the
attributes reported in these fields to have values larger than will
fit in a short container. Therefore, if a COFF program uses
shmctl(2) with the IPC_STAT option, the kernel might not report the
correct values for these attributes.
Note that none of the commands requires the caller to have the shared
segment attached.
ACCESS CONTROL
The access required to the shared memory segment denoted by shmid
depends on the value of cmd, as specified below.
IPC_STAT Get status information. On a generic DG/UX system, the
effective user id of the calling process must equal the
superuser; on a system with DG/UX information security, the
calling process must have appropriate privilege or the
calling process must have read access (SHM_R) as determined
by the mode bits in the ipcperm structure defined by the
shmperm field of the shared memory data structure
associated with shmid.
IPC_SET Set status information. This cmd can be executed by any
process with effective user id equal to either that of
superuser on a traditional DG/UX system, or, on a system
with DG/UX information security, with appropriate privilege
or with effective user id equal to the value of either
shmperm.uid or shmperm.cuid in the ipcperm structure
defined by the shmperm field of the shared memory data
structure associated with shmid.
IPC_RMID Remove shared memory identifier. This cmd can be executed
by any process that, on a traditonal DG/UX system, has an
effective user id equal to either that of superuser, or, on
a system with DG/UX information security, has appropriate
privilege or has an effective user id equal to the value of
either shmperm.uid or shmperm.cuid in the ipcperm
structure defined by the shmperm field of the shared
memory data structure associated with shmid.
RETURN VALUE
0 The shmctl operation was successful.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes for any value of
cmd:
EINVAL Shmid is not a valid shared memory identifier; or cmd is
not a valid command.
The IPC_STAT command may return the following errors:
EFAULT Buf points to an illegal address.
EACCES Read access is denied.
The IPC_SET command may return the following errors:
EFAULT Buf points to an illegal address.
EPERM Access is denied; that is, on a traditional DG/UX system,
the effective user id of the calling process is not
superuser and does not match the shmperm.uid or
shmperm.cuid fields of the shared memory descriptor
associated with shmid, or, on a system with DG/UX
information security, the calling process does not have
appropriate privilege and does not match the shmperm.uid
or shmperm.cuid fields of the shared memory descriptor
associated with shmid.
The IPC_RMID command may return the following error:
EPERM Access is denied; that is, on a traditional DG/UX system,
the effective user id of the calling process is not
superuser and does not match the shmperm.uid or
shmperm.cuid fields of the shared memory descriptor
associated with shmid; or, on a system with DG/UX
information security, the calling process does not have
appropriate privilege and its effective user id does not
match the shmperm.uid or shmperm.cuid fields of the
shared memory descriptor associated with shmid.
SEE ALSO
intro(2), ipcrm(1), ipcs(1), shmget(2), appropriateprivilege(5),
capdefaults(5).
NOTES
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call. On
systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
Licensed material--property of copyright holder(s)