shmget(2) DG/UX 4.30 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)
key_t key;
int size;
int shmflg;
PARAMETERS
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.
Licensed material--property of copyright holder(s) Page 1
shmget(2) DG/UX 4.30 shmget(2)
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:
* Create a private segment - 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 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
Licensed material--property of copyright holder(s) Page 2
shmget(2) DG/UX 4.30 shmget(2)
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 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:
* shm_perm.uid and shm_perm.cuid - set to the effective
user id of the calling process.
* shm_perm.gid and shm_perm.cgid - set to the effective
group id of the calling process.
* shm_perm.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.
* shm_ptbl - set to an implementation-dependent value.
* shm_segsz - set to size.
* shm_lpid - set to 0.
* shm_cpid - set to the process id of the calling
process.
* shm_nattch - set to 0.
* shm_cnattch - set to 0.
* shm_atime - set to 0.
Licensed material--property of copyright holder(s) Page 3
shmget(2) DG/UX 4.30 shmget(2)
* shm_dtime - set to 0.
* shm_ctime - 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 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 shm_perm.mode field of the shared
memory descriptor for the segment. If any mode bit set in
shmflg is not set in shm_perm.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.
EXCEPTIONS
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
Licensed material--property of copyright holder(s) Page 4
shmget(2) DG/UX 4.30 shmget(2)
associated with it is less than size; or
shmflg specifies IPC_EXCL but not IPC_CREAT
(this combination has no defined action).
EACCES A shared memory identifier exists for key but
one of the low-order 9 bits set in shmflg is
not set in the shm_perm.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.
SEE ALSO
intro(2), ipcrm(1), ipcs(1), shmctl(2),
stdipc(3C).
Licensed material--property of copyright holder(s) Page 5