]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2 | .TH "SHMAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" | |
3 | .\" shmat | |
4 | .SH NAME | |
5 | shmat \- XSI shared memory attach operation | |
6 | .SH SYNOPSIS | |
7 | .LP | |
8 | \fB#include <sys/shm.h> | |
9 | .br | |
10 | .sp | |
11 | void *shmat(int\fP \fIshmid\fP\fB, const void *\fP\fIshmaddr\fP\fB, | |
12 | int\fP \fIshmflg\fP\fB); \fP | |
13 | \fB | |
14 | .br | |
15 | \fP | |
16 | .SH DESCRIPTION | |
17 | .LP | |
18 | The \fIshmat\fP() function operates on XSI shared memory (see the | |
19 | Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.340, | |
20 | Shared Memory Object). It is unspecified whether this function | |
21 | interoperates with the realtime interprocess communication facilities | |
22 | defined in \fIRealtime\fP . | |
23 | .LP | |
24 | The \fIshmat\fP() function attaches the shared memory segment associated | |
25 | with the shared memory identifier specified by | |
26 | \fIshmid\fP to the address space of the calling process. The segment | |
27 | is attached at the address specified by one of the following | |
28 | criteria: | |
29 | .IP " *" 3 | |
30 | If \fIshmaddr\fP is a null pointer, the segment is attached at the | |
31 | first available address as selected by the system. | |
32 | .LP | |
33 | .IP " *" 3 | |
34 | If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND) | |
35 | is non-zero, the segment is attached at the address | |
36 | given by (\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)). | |
37 | The character \fB'%'\fP is the C-language remainder | |
38 | operator. | |
39 | .LP | |
40 | .IP " *" 3 | |
41 | If \fIshmaddr\fP is not a null pointer and (\fIshmflg\fP &SHM_RND) | |
42 | is 0, the segment is attached at the address given by | |
43 | \fIshmaddr\fP. | |
44 | .LP | |
45 | .IP " *" 3 | |
46 | The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY) | |
47 | is non-zero and the calling process has read permission; | |
48 | otherwise, if it is 0 and the calling process has read and write permission, | |
49 | the segment is attached for reading and writing. | |
50 | .LP | |
51 | .SH RETURN VALUE | |
52 | .LP | |
53 | Upon successful completion, \fIshmat\fP() shall increment the value | |
54 | of \fIshm_nattch\fP in the data structure associated with | |
55 | the shared memory ID of the attached shared memory segment and return | |
56 | the segment's start address. | |
57 | .LP | |
58 | Otherwise, the shared memory segment shall not be attached, \fIshmat\fP() | |
59 | shall return -1, and \fIerrno\fP shall be set to | |
60 | indicate the error. | |
61 | .SH ERRORS | |
62 | .LP | |
63 | The \fIshmat\fP() function shall fail if: | |
64 | .TP 7 | |
65 | .B EACCES | |
66 | Operation permission is denied to the calling process; see \fIXSI | |
67 | Interprocess | |
68 | Communication\fP . | |
69 | .TP 7 | |
70 | .B EINVAL | |
71 | The value of \fIshmid\fP is not a valid shared memory identifier, | |
72 | the \fIshmaddr\fP is not a null pointer, and the value of | |
73 | (\fIshmaddr\fP -((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)) is an illegal | |
74 | address for attaching shared memory; or the | |
75 | \fIshmaddr\fP is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0, | |
76 | and the value of \fIshmaddr\fP is an illegal address for | |
77 | attaching shared memory. | |
78 | .TP 7 | |
79 | .B EMFILE | |
80 | The number of shared memory segments attached to the calling process | |
81 | would exceed the system-imposed limit. | |
82 | .TP 7 | |
83 | .B ENOMEM | |
84 | The available data space is not large enough to accommodate the shared | |
85 | memory segment. | |
86 | .sp | |
87 | .LP | |
88 | \fIThe following sections are informative.\fP | |
89 | .SH EXAMPLES | |
90 | .LP | |
91 | None. | |
92 | .SH APPLICATION USAGE | |
93 | .LP | |
94 | The POSIX Realtime Extension defines alternative interfaces for interprocess | |
95 | communication. Application developers who need to | |
96 | use IPC should design their applications so that modules using the | |
97 | IPC routines described in \fIXSI Interprocess Communication\fP can | |
98 | be easily modified to use the alternative | |
99 | interfaces. | |
100 | .SH RATIONALE | |
101 | .LP | |
102 | None. | |
103 | .SH FUTURE DIRECTIONS | |
104 | .LP | |
105 | None. | |
106 | .SH SEE ALSO | |
107 | .LP | |
108 | \fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fIexec\fP() | |
109 | , | |
110 | \fIexit\fP() , \fIfork\fP() , \fIshmctl\fP() , \fIshmdt\fP() , \fIshmget\fP() | |
111 | , \fIshm_open\fP() , | |
112 | \fIshm_unlink\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, | |
113 | \fI<sys/shm.h>\fP | |
114 | .SH COPYRIGHT | |
115 | Portions of this text are reprinted and reproduced in electronic form | |
116 | from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology | |
117 | -- Portable Operating System Interface (POSIX), The Open Group Base | |
118 | Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of | |
119 | Electrical and Electronics Engineers, Inc and The Open Group. In the | |
120 | event of any discrepancy between this version and the original IEEE and | |
121 | The Open Group Standard, the original IEEE and The Open Group Standard | |
122 | is the referee document. The original Standard can be obtained online at | |
123 | http://www.opengroup.org/unix/online.html . |