shmget(2) DG/UX 5.4.2 shmget(2)
NAME
shmget - get shared memory segment
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
int shmget (key, size, shmflg)
keyt key;
int size;
int shmflg;
where:
key Key identifying shared memory segment
size Size in bytes of the shared memory segment
shmflg Access and option shmflgs. Valid shmflg bits that may be
set are IPC_CREAT and IPC_EXCL. The low-order 9 bits are
the standard access bits.
DESCRIPTION
The shmget system call returns the shared memory identifier
associated with key. This shared memory identifier may then be used
in other shared memory operations as specified by shmat, shmctl, and
shmdt. Shmget can be used to get the shared memory identifier of an
already existing shared memory segment, or to create a new shared
memory segment.
The size parameter is used in one of two ways, depending on whether
shmget creates a new shared memory segment. When shmget is used to
create a new shared memory segment, size specifies the number of
bytes to make the new shared memory segment. In this case size must
be greater than or equal to a system-imposed minimum size and less
than or equal to a system-imposed maximum size.
When shmget is used to find the shared memory identifier of an
existing shared memory segment, size is used to ensure any such
existing shared memory segment is at least as large as size. This
guarantees that when the shared memory segment is attached, all
references to the shared area whose offsets relative to the start of
the shared area are between 0 and size-1, inclusive, are valid
references to the shared memory segment. If size is greater than the
value of the existing shared memory segment, an error is returned.
If size is less than or equal to the value of the existing shared
segment, the shared memory identifier is returned. This is true even
if the value of size used is less than the system-imposed minimum for
creating shared memory segments. In particular, a size of 0 can
always be specified; this is guaranteed to be less than the actual
size of the shared memory segment and therefore passes this test.
Using the IPC_CREAT and IPC_EXCL shmflgs in shmflg along with the
special key value IPC_PRIVATE, four options are available:
Licensed material--property of copyright holder(s) 1
shmget(2) DG/UX 5.4.2 shmget(2)
⊕ Create a private segment.
In this case, key = IPC_PRIVATE. A process can create a
"private" shared memory identifier by using the special
IPC_PRIVATE key. This results in the system creating a shared
memory identifier that is private to the process. This shared
memory id will not be returned to other processes regardless
of what key value they specify. Note it is really the key
that is "private". The shared memory identifier that is
returned is not private; other processes may use this shared
memory identifier in other shared memory calls. Thus, the
shared memory segment itself is not necessarily private and
accessible only to the calling routine. (For example, the
process could pass the shared memory identifier to another
process via an interprocess message. Even if the process does
not do this, the segment is still accessible to any child
processes created, since a fork operation does an implicit
attach operation; see shmat). A process can make multiple
shmget calls specifying the IPC_PRIVATE key; the shared memory
identifiers returned will be unique and the shared segments
associated will be different. Since this call always creates
a shared segment, size must always be set to the size of the
desired segment. If an error occurs, no shared memory segment
is created and an error is returned.
⊕ Find key if already defined.
In this case, neither the IPC_CREAT nor the IPC_EXCL shmflg
bits are set in shmflg, and key != IPC_PRIVATE. The shared
memory identifier associated with the given key is returned.
If none exists, or if one exists but the size of the
associated segment is less than size, an error is returned.
⊕ Find key if already defined, otherwise create.
In this case, the IPC_CREAT shmflg bit is set, the IPC_EXCL
shmflg bit in shmflg is ignored, and key != IPC_PRIVATE. If a
shared memory identifier already exists for key and the size
of the associated shared memory segment is greater than or
equal to size (note this will be the case if size = 0), the
shared memory identifier is returned. If a shared memory
identifier already exists for key but the size of the
associated shared memory segment is less than size, an error
is returned. If there is no shared memory identifier
corresponding to key, a shared memory segment and an
associated shared memory identifier are created with the
specified key and size. Any errors cause an error to be
returned and do not cause a shared memory segment to be
created.
⊕ Create only if key not currently defined.
In this case, the IPC_CREAT and IPC_EXCL shmflgs are both set
in shmflg, and key != IPC_PRIVATE. If a shared memory
Licensed material--property of copyright holder(s) 2
shmget(2) DG/UX 5.4.2 shmget(2)
identifier already exists for key, an error is returned;
otherwise, a shared memory segment and associated shared
memory identifier are created with the specified key and size.
Since this call attempts to create a shared segment, size must
always be set to the size of the desired segment.
If a shared memory segment is created, the shared memory data
structure associated with the new shared memory identifier is
initialized as follows:
⊕ shmperm.uid and shmperm.cuid - set to the effective user id
of the calling process.
⊕ shmperm.gid and shmperm.cgid - set to the effective group id
of the calling process.
⊕ shmperm.mode - the low-order 9 bits are set to the low-order
9 bits of shmflg. Note these bits determine the access to the
shared memory segment in the standard way: 3 bits for owner,
3 bits for group, 3 bits for other.
⊕ shmptbl - set to an implementation-dependent value.
⊕ shmsegsz - set to size.
⊕ shmlpid - set to 0.
⊕ shmcpid - set to the process id of the calling process.
⊕ shmnattch - set to 0.
⊕ shmcnattch - set to 0.
⊕ shmatime - set to 0.
⊕ shmdtime - set to 0.
⊕ shmctime - set to the current time.
There is a system-imposed maximum on the number of shared memory
segments (and therefore shared memory identifiers) that may exist
simultaneously. Calls to shmget will fail if they require a new
shared memory segment to be created and the system is already at this
limit.
In general, applications wishing to share a memory segment must agree
on a key in some fashion beforehand. One system-defined mechanism
for doing this is the ftok facility, which takes a filename and
returns a process-specific key based on that filename. See the ftok
description in stdipc(3C).
Although no access permission is required to do a shmget operation, a
consistency check is made on the access permissions specified in the
lower 9 bits of shmflg. For any of the options that return the
Licensed material--property of copyright holder(s) 3
shmget(2) DG/UX 5.4.2 shmget(2)
shared memory identifier of an already existing shared memory
segment, a check is made that all mode bits set by the caller in
shmflg are currently set in the shmperm.mode field of the shared
memory descriptor for the segment. If any mode bit set in shmflg is
not set in shmperm.mode, an error is returned. This is not an
access check, because the process calling shmget requires no access
to anything and the shmflg mode bits passed can all be zero. Rather,
it guarantees that the shared memory segment is accessible for the
access modes that may be desired by the caller.
ACCESS CONTROL
No access permission is required to do a shmget operation (except for
the consistency check made on shmflg).
RETURN VALUE
shmid A non-negative integer, namely a shared memory identifier
indicating the shmget 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:
EINVAL A shared memory identifier was to be created but size is
less than the system-imposed minimum or greater than the
system-imposed maximum; or a shared memory identifier
exists for key but the size of the segment associated with
it is less than size and size is not equal to zero.
EACCES A shared memory identifier exists for key but one of the
low-order 9 bits set in shmflg is not set in the
shmperm.mode field of the shared memory identifier's
corresponding shared memory descriptor.
ENOENT A shared memory identifier does not exist for key and the
"create if not already existing" option was not selected,
that is, the IPC_CREAT option was not specified in shmflg.
ENOSPC A shared memory identifier is to be created but the system-
imposed limit on the maximum number of allowed shared
memory identifiers system wide would be exceeded. Another
shared memory segment cannot be created until one is
destroyed.
ENOMEM A shared memory identifier and associated shared memory
segment are to be created but there is not enough internal
system memory available to fill the request. This is
different from ENOSPC in that arbitrary operations that
free internal system memory may allow the call to succeed
at a later time.
EEXIST A shared memory identifier exists for key but the "create
only if not already existing" option was selected, that is,
the IPC_CREAT and IPC_EXCL options were on in shmflg.
Licensed material--property of copyright holder(s) 4
shmget(2) DG/UX 5.4.2 shmget(2)
SEE ALSO
intro(2), ipcrm(1), ipcs(1), shmctl(2), stdipc(3C).
Licensed material--property of copyright holder(s) 5