shmat
Purpose
Attaches a shared memory segment or a mapped file to the
current process.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>
char *shmat (shmid, shmaddr, shmflg)
int shmid;
char *shmaddr;
int shmflg;
Description
The shmat system call attaches the shared memory segment
or mapped file associated with the shared memory identi-
fier (returned by shmget) or file descriptor (returned by
open) specified by the shmid parameter to the address
space of the calling process.
Note: You cannot map a remote file.
The segment or file is attached at the address specified
by the shmaddr parameter as follows:
o If the shmaddr parameter is equal to 0, the segment
or file is attached at the first available address as
selected by the system.
o If the shmaddr parameter is not equal to 0, and
SHM_RND is set in shmflg, the segment or file is
attached at the next lower segment boundary. This
address given by (shmaddr - (shmaddr modulo SHMLBA)).
o If the shmaddr parameter is not equal to 0 and
SHM_RND not set in shmflg, the segment or file is
attached at the address given by the shmaddr param-
eter. If this address does not point to a segment
boundary, then the shmat system call returns the
value -1 and sets errno to EINVAL.
The shmflg parameter specifies several options. Its
value is either 0, or is constructed by logically OR-ing
one or more of the following values:
SHM_RND Rounds the address given by the shmaddr
parameter to the next lower segment
boundary, if necessary.
SHM_MAP Maps a file onto the address space instead
of a shared memory segment. The shmid must
specify an open file descriptor in this
case.
SHM_RDONLY Specifies read-only mode instead of the
default read-write mode.
SHM_COPY Maps a file in copy-on-write mode.
Either SHM_RDONLY or SHM_COPY may be specified, but not
both.
If SHM_MAP is not set in shmflg, then a shared memory
segment is attached to the data segment. It is attached
for reading if SHM_RDONLY is set in shmflg and if the
current process has read permission. If SHM_RDONLY is
not set and the current process has both read and write
permission, then it is attached for reading and writing.
If SHM_MAP is set in shmflg, then file mapping takes
place. In this case, the shmat system call maps the file
open on file descriptor shmid onto a segment. The file
must be a regular file. The segment is then mapped into
the process's address space.
When file mapping is requested, the shmflg parameter
specifies how the file is to be mapped. If SHM_RDONLY is
set, then the file is mapped read-only. If SHM_COPY is
set, then the file is mapped copy-on-write. If neither
of these cases is true, then the file is mapped read-
write. The file must be opened for writing before it can
be mapped read-write or copy-on-write.
All processes that map the same file read-only or read-
write map to the same segment. This segment remains
mapped until the last process mapping the file closes it.
All processes that map the same file copy-on-write map
the same copy-on-write segment. Changes to the shared
segment do not affect the contents of the file resident
in the file system until an fsync system call is issued
for a file descriptor for which copy-on-write mapping was
requested. If a process requests copy-on-write mapping
for a file and the copy-on-write segment does not yet
exist, then it is created, and that segment is maintained
for sharing until the last process attached to it
detaches it with a close system call. When the mapped
file is closed, the segment is detached. The next
request for copy-on-write mapping for the same file
causes a new segment to be created for the file.
A file descriptor can be used to map the corresponding
file only once. A file can be multiply mapped by using
multiple file descriptors. However, a file cannot be
mapped both read-write and copy-on-write by one or more
users at the same time. The results are unpredictable if
a file that one process has mapped copy-on-write is modi-
fied by another process with the write system call,
unless that process has also attached the copy-on-write
segment with a shmat system call.
When a file is mapped onto a segment, the file is refer-
enced by accessing the segment. The memory paging system
automatically takes care of the physical I/O. References
beyond the end of the file cause the file to be extended
in increments of the page size.
Return Value
Upon successful completion, the segment start address of
the attached shared memory segment or mapped file is
returned. If shmat fails, a value of -1 is returned and
errno is set to indicate the error.
Diagnostics
The shmat system call fails and the shared memory segment
or mapped file is not attached if one or more of the fol-
lowing are true:
EACCES Operation permission is denied to the calling
process.
ENOMEM The available data space in memory is not
large enough to hold the shared memory
segment.
ENOMEM The available data space in memory is not
large enough to hold the mapped file data
structure.
EINVAL The shmid parameter is not a valid shared
memory identifier, or the file to be mapped
resides in a remote node.
EINVAL The shmaddr parameter is not equal to 0, and
the value of (shmaddr - (shmaddr modulo
SHMLBA)) &pointsout..
EINVAL The shmaddr parameter is not equal to 0,
SHM_RND is not set in shmflg, and the the
shmaddr parameter &pointsout..
EINVAL The shmaddr parameter is not equal to 0,
SHM_RND is not set in shmflg, and the the
shmaddr parameter does not point to a segment
boundary.
EEXIST The file to be mapped has already been mapped.
ETXTBSY The shmat system call attempted to map a file
onto a segment attached to a shared library.
EMFILE The number of shared memory segments attached
to the calling process would exceed the
system-imposed limit.
EBADF A file descriptor to map does not refer to an
open regular file, or both read-only and copy-
on-write modes were requested.
EACCES A file to be mapped is open read-only, but the
segment is to be mapped read-write or copy-on-
write.
EACCES The file is to be mapped read-write, but the
file is currently mapped copy-on-write; or the
file is to be mapped copy-on-write, but it is
currently mapped read-write.
EACCES The file to be mapped has enforced locking
enabled, and the file is currently locked.
EFBIG The file to be mapped is larger than the
maximum size of a segment.
Related Information
In this book: "exec: execl, execv, execle, execve,
execlp, execvp," "exit, _exit," "fclear," "fork,"
"fsync," "ftruncate," "read, readx," "shmctl," "shmdt,"
"shmget," and "write, writex."