436 lines
9.1 KiB
HTML
436 lines
9.1 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SHMOP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SHMOP</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-08-02<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
shmat, shmdt - System V shared memory operations
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/sys/types.h">sys/types.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/sys/shm.h">sys/shm.h</A>></B>
|
|
|
|
<B>void *shmat(int </B><I>shmid</I><B>, const void *</B><I>shmaddr</I><B>, int </B><I>shmflg</I><B>);</B>
|
|
|
|
<B>int shmdt(const void *</B><I>shmaddr</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>shmat()</H3>
|
|
|
|
<B>shmat</B>()
|
|
|
|
attaches the System V shared memory segment identified by
|
|
<I>shmid</I>
|
|
|
|
to the address space of the calling process.
|
|
The attaching address is specified by
|
|
<I>shmaddr</I>
|
|
|
|
with one of the following criteria:
|
|
<DL COMPACT>
|
|
<DT id="1">*<DD>
|
|
If
|
|
<I>shmaddr</I>
|
|
|
|
is NULL,
|
|
the system chooses a suitable (unused) page-aligned address to attach
|
|
the segment.
|
|
<DT id="2">*<DD>
|
|
If
|
|
<I>shmaddr</I>
|
|
|
|
isn't NULL
|
|
and
|
|
<B>SHM_RND</B>
|
|
|
|
is specified in
|
|
<I>shmflg</I>,
|
|
|
|
the attach occurs at the address equal to
|
|
<I>shmaddr</I>
|
|
|
|
rounded down to the nearest multiple of
|
|
<B>SHMLBA</B>.
|
|
|
|
<DT id="3">*<DD>
|
|
Otherwise,
|
|
<I>shmaddr</I>
|
|
|
|
must be a page-aligned address at which the attach occurs.
|
|
</DL>
|
|
<P>
|
|
|
|
In addition to
|
|
<B>SHM_RND</B>,
|
|
|
|
the following flags may be specified in the
|
|
<I>shmflg</I>
|
|
|
|
bit-mask argument:
|
|
<DL COMPACT>
|
|
<DT id="4"><B>SHM_EXEC</B> (Linux-specific; since Linux 2.6.9)
|
|
|
|
<DD>
|
|
Allow the contents of the segment to be executed.
|
|
The caller must have execute permission on the segment.
|
|
<DT id="5"><B>SHM_RDONLY</B>
|
|
|
|
<DD>
|
|
Attach the segment for read-only access.
|
|
The process must have read permission for the segment.
|
|
If this flag is not specified,
|
|
the segment is attached for read and write access,
|
|
and the process must have read and write permission for the segment.
|
|
There is no notion of a write-only shared memory segment.
|
|
<DT id="6"><B>SHM_REMAP</B> (Linux-specific)
|
|
|
|
<DD>
|
|
This flag specifies
|
|
that the mapping of the segment should replace
|
|
any existing mapping in the range starting at
|
|
<I>shmaddr</I>
|
|
|
|
and continuing for the size of the segment.
|
|
(Normally, an
|
|
<B>EINVAL</B>
|
|
|
|
error would result if a mapping already exists in this address range.)
|
|
In this case,
|
|
<I>shmaddr</I>
|
|
|
|
must not be NULL.
|
|
</DL>
|
|
<P>
|
|
|
|
The
|
|
<B><A HREF="/cgi-bin/man/man2html?2+brk">brk</A></B>(2)
|
|
|
|
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.
|
|
<P>
|
|
|
|
A successful
|
|
<B>shmat</B>()
|
|
|
|
call updates the members of the
|
|
<I>shmid_ds</I>
|
|
|
|
structure (see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+shmctl">shmctl</A></B>(2))
|
|
|
|
associated with the shared memory segment as follows:
|
|
<DL COMPACT>
|
|
<DT id="7"><DD>
|
|
<I>shm_atime</I>
|
|
|
|
is set to the current time.
|
|
<DT id="8"><DD>
|
|
<I>shm_lpid</I>
|
|
|
|
is set to the process-ID of the calling process.
|
|
<DT id="9"><DD>
|
|
<I>shm_nattch</I>
|
|
|
|
is incremented by one.
|
|
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>shmdt()</H3>
|
|
|
|
<B>shmdt</B>()
|
|
|
|
detaches the shared memory segment located at the address specified by
|
|
<I>shmaddr</I>
|
|
|
|
from the address space of the calling process.
|
|
The to-be-detached segment must be currently
|
|
attached with
|
|
<I>shmaddr</I>
|
|
|
|
equal to the value returned by the attaching
|
|
<B>shmat</B>()
|
|
|
|
call.
|
|
<P>
|
|
|
|
On a successful
|
|
<B>shmdt</B>()
|
|
|
|
call, the system updates the members of the
|
|
<I>shmid_ds</I>
|
|
|
|
structure associated with the shared memory segment as follows:
|
|
<DL COMPACT>
|
|
<DT id="10"><DD>
|
|
<I>shm_dtime</I>
|
|
|
|
is set to the current time.
|
|
<DT id="11"><DD>
|
|
<I>shm_lpid</I>
|
|
|
|
is set to the process-ID of the calling process.
|
|
<DT id="12"><DD>
|
|
<I>shm_nattch</I>
|
|
|
|
is decremented by one.
|
|
If it becomes 0 and the segment is marked for deletion,
|
|
the segment is deleted.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success,
|
|
<B>shmat</B>()
|
|
|
|
returns the address of the attached shared memory segment; on error,
|
|
<I>(void *) -1</I>
|
|
|
|
is returned, and
|
|
<I>errno</I>
|
|
|
|
is set to indicate the cause of the error.
|
|
<P>
|
|
|
|
On success,
|
|
<B>shmdt</B>()
|
|
|
|
returns 0; on error -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set to indicate the cause of the error.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
When
|
|
<B>shmat</B>()
|
|
|
|
fails,
|
|
<I>errno</I>
|
|
|
|
is set to one of the following:
|
|
<DL COMPACT>
|
|
<DT id="13"><B>EACCES</B>
|
|
|
|
<DD>
|
|
The calling process does not have the required permissions for
|
|
the requested attach type, and does not have the
|
|
<B>CAP_IPC_OWNER</B>
|
|
|
|
capability in the user namespace that governs its IPC namespace.
|
|
<DT id="14"><B>EIDRM</B>
|
|
|
|
<DD>
|
|
<I>shmid</I> points to a removed identifier.
|
|
<DT id="15"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
Invalid
|
|
<I>shmid</I>
|
|
|
|
value, unaligned (i.e., not page-aligned and <B>SHM_RND</B> was not
|
|
specified) or invalid
|
|
<I>shmaddr</I>
|
|
|
|
value, or can't attach segment at
|
|
<I>shmaddr</I>,
|
|
|
|
or
|
|
<B>SHM_REMAP</B>
|
|
|
|
was specified and
|
|
<I>shmaddr</I>
|
|
|
|
was NULL.
|
|
<DT id="16"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
Could not allocate memory for the descriptor or for the page tables.
|
|
</DL>
|
|
<P>
|
|
|
|
When
|
|
<B>shmdt</B>()
|
|
|
|
fails,
|
|
<I>errno</I>
|
|
|
|
is set as follows:
|
|
<DL COMPACT>
|
|
<DT id="17"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
There is no shared memory segment attached at
|
|
<I>shmaddr</I>;
|
|
|
|
or,
|
|
|
|
<I>shmaddr</I>
|
|
|
|
is not aligned on a page boundary.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
|
|
<P>
|
|
|
|
In SVID 3 (or perhaps earlier),
|
|
the type of the <I>shmaddr</I> argument was changed from
|
|
<I>char *</I>
|
|
|
|
into
|
|
<I>const void *</I>,
|
|
|
|
and the returned type of
|
|
<B>shmat</B>()
|
|
|
|
from
|
|
<I>char *</I>
|
|
|
|
into
|
|
<I>void *</I>.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<P>
|
|
|
|
After a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fork">fork</A></B>(2),
|
|
|
|
the child inherits the attached shared memory segments.
|
|
<P>
|
|
|
|
After an
|
|
<B><A HREF="/cgi-bin/man/man2html?2+execve">execve</A></B>(2),
|
|
|
|
all attached shared memory segments are detached from the process.
|
|
<P>
|
|
|
|
Upon
|
|
<B><A HREF="/cgi-bin/man/man2html?2+_exit">_exit</A></B>(2),
|
|
|
|
all attached shared memory segments are detached from the process.
|
|
<P>
|
|
|
|
Using
|
|
<B>shmat</B>()
|
|
|
|
with
|
|
<I>shmaddr</I>
|
|
|
|
equal to NULL
|
|
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.
|
|
<P>
|
|
|
|
On Linux, it is possible to attach a shared memory segment even if it
|
|
is already marked to be deleted.
|
|
However, POSIX.1 does not specify this behavior and
|
|
many other implementations do not support it.
|
|
<P>
|
|
|
|
The following system parameter affects
|
|
<B>shmat</B>():
|
|
|
|
<DL COMPACT>
|
|
<DT id="18"><B>SHMLBA</B>
|
|
|
|
<DD>
|
|
Segment low boundary address multiple.
|
|
When explicitly specifying an attach address in a call to
|
|
<B>shmat</B>(),
|
|
|
|
the caller should ensure that the address is a multiple of this value.
|
|
This is necessary on some architectures,
|
|
in order either to ensure good CPU cache performance or to ensure that
|
|
different attaches of the same segment have consistent views
|
|
within the CPU cache.
|
|
<B>SHMLBA</B>
|
|
|
|
is normally some multiple of the system page size.
|
|
(On many Linux architectures,
|
|
<B>SHMLBA</B>
|
|
|
|
is the same as the system page size.)
|
|
</DL>
|
|
<P>
|
|
|
|
The implementation places no intrinsic per-process limit on the
|
|
number of shared memory segments
|
|
(<B>SHMSEG</B>).
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+brk">brk</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+shmctl">shmctl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+shmget">shmget</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+capabilities">capabilities</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+shm_overview">shm_overview</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+sysvipc">sysvipc</A></B>(7)
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="19"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="20"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="21"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="22"><A HREF="#lbAE">shmat()</A><DD>
|
|
<DT id="23"><A HREF="#lbAF">shmdt()</A><DD>
|
|
</DL>
|
|
<DT id="24"><A HREF="#lbAG">RETURN VALUE</A><DD>
|
|
<DT id="25"><A HREF="#lbAH">ERRORS</A><DD>
|
|
<DT id="26"><A HREF="#lbAI">CONFORMING TO</A><DD>
|
|
<DT id="27"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DT id="28"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="29"><A HREF="#lbAL">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:34 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|