2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2004-11-10 17:25:44 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2004-11-10 17:25:44 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu)
|
|
|
|
.\" with material from Luigi P. Bai (lpb@softint.com)
|
|
|
|
.\" Portions Copyright 1993 Luigi P. Bai
|
|
|
|
.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com>
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 5 Jan 2002, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Modified, 19 Sep 2002, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added SHM_REMAP flag description
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
2004-11-10 17:25:44 +00:00
|
|
|
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Language and formatting clean-ups
|
|
|
|
.\" Changed wording and placement of sentence regarding attachment
|
|
|
|
.\" of segments marked for destruction
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2004-11-10 17:25:44 +00:00
|
|
|
.TH SHMOP 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
shmop \- shared memory operations
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B
|
|
|
|
#include <sys/types.h>
|
|
|
|
.B
|
|
|
|
#include <sys/shm.h>
|
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
.BI "void *shmat(int " shmid ,
|
|
|
|
.BI "const void *" shmaddr ,
|
|
|
|
.BI "int " shmflg );
|
|
|
|
.sp
|
|
|
|
.BI "int shmdt(const void *" shmaddr );
|
|
|
|
.SH DESCRIPTION
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmat ()
|
2004-11-03 13:51:07 +00:00
|
|
|
attaches the shared memory segment identified by
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shmid
|
2004-11-03 13:51:07 +00:00
|
|
|
to the address space of the calling process.
|
|
|
|
The attaching address is specified by
|
|
|
|
.I shmaddr
|
|
|
|
with one of the following criteria:
|
|
|
|
.LP
|
|
|
|
If
|
|
|
|
.I shmaddr
|
2005-11-02 13:55:25 +00:00
|
|
|
is NULL,
|
2004-11-03 13:51:07 +00:00
|
|
|
the system chooses a suitable (unused) address at which to attach
|
|
|
|
the segment.
|
|
|
|
.LP
|
|
|
|
If
|
|
|
|
.I shmaddr
|
2005-11-02 13:55:25 +00:00
|
|
|
isn't NULL
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
|
|
|
.B SHM_RND
|
2004-11-10 17:25:44 +00:00
|
|
|
is specified in
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR shmflg ,
|
|
|
|
the attach occurs at the address equal to
|
|
|
|
.I shmaddr
|
|
|
|
rounded down to the nearest multiple of
|
|
|
|
.BR SHMLBA .
|
|
|
|
Otherwise
|
|
|
|
.I shmaddr
|
|
|
|
must be a page-aligned address at which the attach occurs.
|
|
|
|
.PP
|
|
|
|
If
|
|
|
|
.B SHM_RDONLY
|
2004-11-10 17:25:44 +00:00
|
|
|
is specified in
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR shmflg ,
|
|
|
|
the segment is attached for reading and the process must have
|
|
|
|
read permission for the segment.
|
|
|
|
Otherwise the segment is attached for read and write
|
|
|
|
and the process must have read and write permission for the segment.
|
|
|
|
There is no notion of a write-only shared memory segment.
|
|
|
|
.PP
|
|
|
|
The (Linux-specific)
|
|
|
|
.B SHM_REMAP
|
2004-11-10 17:25:44 +00:00
|
|
|
flag may be specified in
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shmflg
|
|
|
|
to indicate that the mapping of the segment should replace
|
2004-11-10 17:25:44 +00:00
|
|
|
any existing mapping in the range starting at
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shmaddr
|
|
|
|
and continuing for the size of the segment.
|
|
|
|
(Normally an
|
|
|
|
.B EINVAL
|
|
|
|
error would result if a mapping already exists in this address range.)
|
|
|
|
In this case,
|
|
|
|
.I shmaddr
|
2005-11-02 13:55:25 +00:00
|
|
|
must not be NULL.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR brk (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
value of the calling process is not altered by the attach.
|
|
|
|
The segment will automatically be detached at process exit.
|
|
|
|
The same segment may be attached as a read and as a read-write
|
|
|
|
one, and more than once, in the process's address space.
|
|
|
|
.PP
|
2004-11-10 17:25:44 +00:00
|
|
|
A successful
|
|
|
|
.BR shmat ()
|
|
|
|
call updates the members of the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B shmid_ds
|
2004-11-10 17:25:44 +00:00
|
|
|
structure (see
|
|
|
|
.BR shmctl (2))
|
|
|
|
associated with the shared memory segment as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_atime
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the current time.
|
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_lpid
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the process-ID of the calling process.
|
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_nattch
|
2004-11-03 13:51:07 +00:00
|
|
|
is incremented by one.
|
|
|
|
.PP
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmdt ()
|
2004-11-03 13:51:07 +00:00
|
|
|
detaches the shared memory segment located at the address specified by
|
|
|
|
.I shmaddr
|
|
|
|
from the address space of the calling process.
|
|
|
|
The to\-be\-detached segment must be currently
|
|
|
|
attached with
|
|
|
|
.I shmaddr
|
2004-11-10 17:25:44 +00:00
|
|
|
equal to the value returned by the attaching
|
|
|
|
.BR shmat ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call.
|
|
|
|
.PP
|
|
|
|
On a successful
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmdt ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call the system updates the members of the
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shmid_ds
|
2004-11-03 13:51:07 +00:00
|
|
|
structure associated with the shared memory segment as follows:
|
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_dtime
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the current time.
|
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_lpid
|
2004-11-03 13:51:07 +00:00
|
|
|
is set to the process-ID of the calling process.
|
|
|
|
.IP
|
2004-11-10 17:25:44 +00:00
|
|
|
.I shm_nattch
|
2004-11-03 13:51:07 +00:00
|
|
|
is decremented by one.
|
|
|
|
If it becomes 0 and the segment is marked for deletion,
|
|
|
|
the segment is deleted.
|
|
|
|
.SH "SYSTEM CALLS"
|
|
|
|
.TP 11
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR fork ()
|
2004-11-03 13:51:07 +00:00
|
|
|
After a
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR fork ()
|
2004-11-03 13:51:07 +00:00
|
|
|
the child inherits the attached shared memory segments.
|
|
|
|
.TP
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
After an
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
all attached shared memory segments are detached from the process.
|
|
|
|
.TP
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR exit ()
|
2004-11-03 13:51:07 +00:00
|
|
|
Upon
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR exit ()
|
2004-11-03 13:51:07 +00:00
|
|
|
all attached shared memory segments are detached from the process.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmat ()
|
2005-12-02 08:09:44 +00:00
|
|
|
returns the address of the attached shared memory segment; on error
|
|
|
|
.I (void *) \-1
|
|
|
|
is returned, and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the cause of the error.
|
|
|
|
|
|
|
|
On success
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmdt ()
|
2005-12-02 08:09:44 +00:00
|
|
|
returns 0; on error \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
2005-12-02 08:09:44 +00:00
|
|
|
is set to indicate the cause of the error.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
When
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmat ()
|
2004-11-03 13:51:07 +00:00
|
|
|
fails,
|
|
|
|
.I errno
|
|
|
|
is set to one of the following:
|
|
|
|
.TP
|
|
|
|
.B EACCES
|
|
|
|
The calling process does not have the required permissions for
|
|
|
|
the requested attach type, and does not have the
|
|
|
|
.B CAP_IPC_OWNER
|
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Invalid
|
|
|
|
.I shmid
|
|
|
|
value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not
|
|
|
|
specified) or invalid
|
|
|
|
.I shmaddr
|
|
|
|
value, or failing attach at
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR brk (),
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" FIXME What does "failing attach at brk" mean? (Is this phrase
|
|
|
|
.\" just junk?)
|
2004-11-10 17:25:44 +00:00
|
|
|
or
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SHM_REMAP
|
|
|
|
was specified and
|
|
|
|
.I shmaddr
|
2005-11-02 13:55:25 +00:00
|
|
|
was NULL.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Could not allocate memory for the descriptor or for the page tables.
|
|
|
|
.PP
|
2006-04-04 02:59:37 +00:00
|
|
|
When
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmdt ()
|
2006-04-04 02:59:37 +00:00
|
|
|
fails,
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
2006-04-04 02:59:37 +00:00
|
|
|
is set as follows:
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
There is no shared memory segment attached at
|
|
|
|
.IR shmaddr ;
|
|
|
|
or,
|
|
|
|
.\" The following since 2.6.17-rc1:
|
|
|
|
.I shmaddr
|
|
|
|
is not aligned on a page boundary.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
|
|
|
Using
|
2004-11-10 17:25:44 +00:00
|
|
|
.BR shmat ()
|
2004-11-03 13:51:07 +00:00
|
|
|
with
|
|
|
|
.I shmaddr
|
2005-11-02 13:55:25 +00:00
|
|
|
equal to NULL
|
2004-11-03 13:51:07 +00:00
|
|
|
is the preferred, portable way of attaching a shared memory segment.
|
|
|
|
Be aware that the shared memory segment attached in this way
|
|
|
|
may be attached at different addresses in different processes.
|
|
|
|
Therefore, any pointers maintained within the shared memory must be
|
|
|
|
made relative (typically to the starting address of the segment),
|
|
|
|
rather than absolute.
|
2004-11-10 17:25:44 +00:00
|
|
|
.PP
|
|
|
|
On Linux, it is possible to attach a shared memory segment even if it
|
2005-06-29 09:19:41 +00:00
|
|
|
is already marked to be deleted.
|
2004-11-10 17:25:44 +00:00
|
|
|
However, POSIX.1-2001 does not specify this behaviour and
|
|
|
|
many other implementations do not support it.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2004-11-10 17:25:44 +00:00
|
|
|
The following system parameter affects
|
|
|
|
.BR shmat ():
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP 11
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" FIXME A good explanation of the rationale for the existence
|
|
|
|
.\" of SHMLBA would be useful here
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SHMLBA
|
|
|
|
Segment low boundary address multiple.
|
|
|
|
Must be page aligned.
|
|
|
|
For the current implementation the
|
2005-03-31 12:59:18 +00:00
|
|
|
.B SHMLBA
|
2004-11-03 13:51:07 +00:00
|
|
|
value is
|
|
|
|
.BR PAGE_SIZE .
|
2004-11-10 17:25:44 +00:00
|
|
|
.\" FIXME That last sentence isn't true for all Linux
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" architectures (i.e., SHMLBA != PAGE_SIZE for some architectures)
|
|
|
|
.\" -- MTK, Nov 04
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2004-12-13 08:39:46 +00:00
|
|
|
The implementation places no intrinsic limit on the per\-process maximum
|
2004-11-03 13:51:07 +00:00
|
|
|
number of shared memory segments
|
|
|
|
.RB ( SHMSEG ).
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:17 +00:00
|
|
|
SVr4, POSIX.1-2001.
|
|
|
|
.\" SVr4 documents an additional error condition EMFILE.
|
|
|
|
|
|
|
|
In SVID 3 (or perhaps earlier)
|
|
|
|
the type of the \fIshmaddr\fP argument was changed from
|
2006-09-04 08:57:04 +00:00
|
|
|
.I "char *"
|
2004-11-03 13:51:07 +00:00
|
|
|
into
|
2006-09-04 08:57:04 +00:00
|
|
|
.IR "const void *" ,
|
2004-11-03 13:51:07 +00:00
|
|
|
and the returned type of \fIshmat\fP() from
|
2006-09-04 08:57:04 +00:00
|
|
|
.I "char *"
|
2004-11-03 13:51:07 +00:00
|
|
|
into
|
2006-09-04 08:57:04 +00:00
|
|
|
.IR "void *" .
|
2004-11-03 13:51:07 +00:00
|
|
|
(Linux libc4 and libc5 have the
|
2006-09-04 08:57:04 +00:00
|
|
|
.I "char *"
|
2004-11-03 13:51:07 +00:00
|
|
|
prototypes; glibc2 has
|
2006-09-04 08:57:04 +00:00
|
|
|
.IR "void *" .)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR brk (2),
|
|
|
|
.BR mmap (2),
|
|
|
|
.BR shmctl (2),
|
|
|
|
.BR shmget (2),
|
2006-04-21 00:38:38 +00:00
|
|
|
.BR capabilities (7),
|
2006-04-21 03:53:43 +00:00
|
|
|
.BR svipc (7)
|