shmget(2)
_________________________________________________________________
shmget System Call
Get shared memory segment.
_________________________________________________________________
SYNTAX
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
int shmget (key, size, flag)
key_t key;
int size;
int flag;
PARAMETERS
key Key identifying shared memory segment.
size Size in bytes of the shared memory segment.
flag Access and option flags. Valid flag bits that may
be set are IPC_CREAT and IPC_EXCL. The low-order 9
bits are the standard access bits.
DESCRIPTION
Shmget 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>.
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
shmget(2)
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 flags in <flag> 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 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 flag
bits are set in <flag>, 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 flag bit is set the IPC_EXCL flag
bit in <flag> is ignored, and <key> != IPC_PRIVATE. If a
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
shmget(2)
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 is 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 flags are both set
in <flag>, 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 is 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 <flag>. 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.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
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(3).
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 <flag>. 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 <flag> are currently set in the shm_perm.mode field
of the shared memory descriptor for the segment. If any mode bit
set in <flag> is not set in shm_perm.mode, an error is returned.
This is not an access check, since the process calling shmget
requires no access to anything, and since the passed in <flag>
mode bits 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.
[Note, however, the consistency check made on <flag>.]
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:
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
shmget(2)
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.
EINVAL A shared memory identifier exists for <key> but
the size of the segment associated with it is less
than <size>.
EINVAL <flag> 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 <flag> 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, i.e., the IPC_CREAT
option was not specified in <flag>.
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, i.e., the IPC_CREAT and IPC_EXCL
options were on in <flag>.
SEE ALSO
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
shmget(2)
The related system calls: intro(2), shmctl(2), shmop(2),
stdipc(3).
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)