shmat(2)

1SHMOP(2)                   Linux Programmer's Manual                  SHMOP(2)
2
3
4

NAME

6       shmop - shared memory operations
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/shm.h>
11
12       void *shmat(int shmid, const void *shmaddr, int shmflg);
13
14       int shmdt(const void *shmaddr);
15

DESCRIPTION

17       shmat()  attaches  the shared memory segment identified by shmid to the
18       address space of the calling process.  The attaching address is  speci‐
19       fied by shmaddr with one of the following criteria:
20
21       If  shmaddr  is NULL, the system chooses a suitable (unused) address at
22       which to attach the segment.
23
24       If shmaddr isn't NULL and SHM_RND is specified in  shmflg,  the  attach
25       occurs at the address equal to shmaddr rounded down to the nearest mul‐
26       tiple of SHMLBA.  Otherwise shmaddr must be a page-aligned  address  at
27       which the attach occurs.
28
29       If SHM_RDONLY is specified in shmflg, the segment is attached for read‐
30       ing and the process must have read permission for the segment.   Other‐
31       wise  the  segment  is attached for read and write and the process must
32       have read and write permission for the segment.  There is no notion  of
33       a write-only shared memory segment.
34
35       The (Linux-specific) SHM_REMAP flag may be specified in shmflg to indi‐
36       cate that the mapping of the segment should replace any  existing  map‐
37       ping  in  the  range starting at shmaddr and continuing for the size of
38       the segment.  (Normally an EINVAL  error  would  result  if  a  mapping
39       already  exists in this address range.)  In this case, shmaddr must not
40       be NULL.
41
42       The brk(2) value of the calling process is not altered by  the  attach.
43       The  segment  will automatically be detached at process exit.  The same
44       segment may be attached as a read and as a  read-write  one,  and  more
45       than once, in the process's address space.
46
47       A successful shmat() call updates the members of the shmid_ds structure
48       (see shmctl(2)) associated with the shared memory segment as follows:
49
50              shm_atime is set to the current time.
51
52              shm_lpid is set to the process-ID of the calling process.
53
54              shm_nattch is incremented by one.
55
56       shmdt() detaches the shared memory segment located at the address spec‐
57       ified  by  shmaddr  from the address space of the calling process.  The
58       to-be-detached segment must be currently attached with shmaddr equal to
59       the value returned by the attaching shmat() call.
60
61       On  a  successful  shmdt()  call  the system updates the members of the
62       shmid_ds structure associated with the shared memory  segment  as  fol‐
63       lows:
64
65              shm_dtime is set to the current time.
66
67              shm_lpid is set to the process-ID of the calling process.
68
69              shm_nattch  is decremented by one.  If it becomes 0 and the seg‐
70              ment is marked for deletion, the segment is deleted.
71

SYSTEM CALLS

73       fork()     After a fork() the child inherits the attached shared memory
74                  segments.
75
76       exec()     After  an  exec()  all  attached  shared memory segments are
77                  detached from the process.
78
79       exit()     Upon exit() all attached shared memory segments are detached
80                  from the process.
81

RETURN VALUE

83       On  success  shmat()  returns the address of the attached shared memory
84       segment; on error (void *) -1 is returned, and errno is set to indicate
85       the cause of the error.
86
87       On success shmdt() returns 0; on error -1 is returned, and errno is set
88       to indicate the cause of the error.
89

ERRORS

91       When shmat() fails, errno is set to one of the following:
92
93       EACCES The calling process does not have the required  permissions  for
94              the  requested  attach type, and does not have the CAP_IPC_OWNER
95              capability.
96
97       EINVAL Invalid shmid  value,  unaligned  (i.e.,  not  page-aligned  and
98              SHM_RND  was not specified) or invalid shmaddr value, or failing
99              attach at brk(), or SHM_REMAP  was  specified  and  shmaddr  was
100              NULL.
101
102       ENOMEM Could  not  allocate  memory  for the descriptor or for the page
103              tables.
104
105       When shmdt() fails, errno is set as follows:
106
107       EINVAL There is no shared  memory  segment  attached  at  shmaddr;  or,
108              shmaddr is not aligned on a page boundary.
109

NOTES

111       Using shmat() with shmaddr equal to NULL is the preferred, portable way
112       of attaching a shared memory segment.  Be aware that the shared  memory
113       segment  attached in this way may be attached at different addresses in
114       different processes.  Therefore, any  pointers  maintained  within  the
115       shared  memory must be made relative (typically to the starting address
116       of the segment), rather than absolute.
117
118       On Linux, it is possible to attach a shared memory segment even  if  it
119       is  already marked to be deleted.  However, POSIX.1-2001 does not spec‐
120       ify this behaviour and many other implementations do not support it.
121
122       The following system parameter affects shmat():
123
124       SHMLBA     Segment  low  boundary  address  multiple.   Must  be   page
125                  aligned.  For the current implementation the SHMLBA value is
126                  PAGE_SIZE.
127
128       The implementation places no intrinsic limit on the per-process maximum
129       number of shared memory segments (SHMSEG).
130

CONFORMING TO

132       SVr4, POSIX.1-2001.
133
134       In  SVID  3  (or  perhaps earlier) the type of the shmaddr argument was
135       changed from char * into const void *, and the returned type of shmat()
136       from char * into void *.  (Linux libc4 and libc5 have the char * proto‐
137       types; glibc2 has void *.)
138