logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

shmat.3p (5031B)

    

  1. '\" et
  2. .TH SHMAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. shmat
  12. \(em XSI shared memory attach operation
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/shm.h>
  17. .P
  18. void *shmat(int \fIshmid\fP, const void *\fIshmaddr\fP, int \fIshmflg\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIshmat\fR()
  23. function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2017,
  24. .IR "Section 3.346" ", " "Shared Memory Object").
  25. It is unspecified whether this function interoperates with the
  26. realtime interprocess communication facilities defined in
  27. .IR "Section 2.8" ", " "Realtime".
  28. .P
  29. The
  30. \fIshmat\fR()
  31. function attaches the shared memory segment associated with the shared
  32. memory identifier specified by
  33. .IR shmid
  34. to the address space of the calling process. The segment is attached
  35. at the address specified by one of the following criteria:
  36. .IP " *" 4
  37. If
  38. .IR shmaddr
  39. is a null pointer, the segment is attached at the first available
  40. address as selected by the system.
  41. .IP " *" 4
  42. If
  43. .IR shmaddr
  44. is not a null pointer and (\fIshmflg\fP &SHM_RND)
  45. is non-zero, the segment is attached at the address given by
  46. (\fIshmaddr\fP \-((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)). The
  47. character
  48. .BR '%' 
  49. is the C-language remainder operator.
  50. .IP " *" 4
  51. If
  52. .IR shmaddr
  53. is not a null pointer and (\fIshmflg\fP &SHM_RND) is 0, the segment is
  54. attached at the address given by
  55. .IR shmaddr .
  56. .IP " *" 4
  57. The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY)
  58. is non-zero and the calling process has read permission; otherwise, if
  59. it is 0 and the calling process has read and write permission, the
  60. segment is attached for reading and writing.
  61. .SH "RETURN VALUE"
  62. Upon successful completion,
  63. \fIshmat\fR()
  64. shall increment the value of
  65. .IR shm_nattch
  66. in the data structure associated with the shared memory ID of the
  67. attached shared memory segment and return the segment's start address.
  68. Also, the
  69. .IR shm_atime
  70. timestamp shall be set to the current time, as described in
  71. .IR "Section 2.7.1" ", " "IPC General Description".
  72. .P
  73. Otherwise, the shared memory segment shall not be attached,
  74. \fIshmat\fR()
  75. shall return (\fBvoid *\fP)\-1, and
  76. .IR errno
  77. shall be set to indicate the error.
  78. .SH ERRORS
  79. The
  80. \fIshmat\fR()
  81. function shall fail if:
  82. .TP
  83. .BR EACCES
  84. Operation permission is denied to the calling process; see
  85. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  86. .TP
  87. .BR EINVAL
  88. The value of
  89. .IR shmid
  90. is not a valid shared memory identifier, the
  91. .IR shmaddr
  92. is not a null pointer, and the value of
  93. (\fIshmaddr\fP \-((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA))
  94. is an illegal address for attaching shared memory; or the
  95. .IR shmaddr
  96. is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0, and the value of
  97. .IR shmaddr
  98. is an illegal address for attaching shared memory.
  99. .TP
  100. .BR EMFILE
  101. The number of shared memory segments attached to the calling process
  102. would exceed the system-imposed limit.
  103. .TP
  104. .BR ENOMEM
  105. The available data space is not large enough to accommodate the shared
  106. memory segment.
  107. .LP
  108. .IR "The following sections are informative."
  109. .SH EXAMPLES
  110. None.
  111. .SH "APPLICATION USAGE"
  112. The POSIX Realtime Extension defines alternative interfaces for interprocess
  113. communication. Application developers who need to use IPC should
  114. design their applications so that modules using the IPC routines
  115. described in
  116. .IR "Section 2.7" ", " "XSI Interprocess Communication"
  117. can be easily modified to use the alternative interfaces.
  118. .SH RATIONALE
  119. None.
  120. .SH "FUTURE DIRECTIONS"
  121. None.
  122. .SH "SEE ALSO"
  123. .IR "Section 2.7" ", " "XSI Interprocess Communication",
  124. .IR "Section 2.8" ", " "Realtime",
  125. .IR "\fIexec\fR\^",
  126. .IR "\fIexit\fR\^(\|)",
  127. .IR "\fIfork\fR\^(\|)",
  128. .IR "\fIshmctl\fR\^(\|)",
  129. .IR "\fIshmdt\fR\^(\|)",
  130. .IR "\fIshmget\fR\^(\|)",
  131. .IR "\fIshm_open\fR\^(\|)",
  132. .IR "\fIshm_unlink\fR\^(\|)"
  133. .P
  134. The Base Definitions volume of POSIX.1\(hy2017,
  135. .IR "Section 3.346" ", " "Shared Memory Object",
  136. .IR "\fB<sys_shm.h>\fP"
  137. .\"
  138. .SH COPYRIGHT
  139. Portions of this text are reprinted and reproduced in electronic form
  140. from IEEE Std 1003.1-2017, Standard for Information Technology
  141. -- Portable Operating System Interface (POSIX), The Open Group Base
  142. Specifications Issue 7, 2018 Edition,
  143. Copyright (C) 2018 by the Institute of
  144. Electrical and Electronics Engineers, Inc and The Open Group.
  145. In the event of any discrepancy between this version and the original IEEE and
  146. The Open Group Standard, the original IEEE and The Open Group Standard
  147. is the referee document. The original Standard can be obtained online at
  148. http://www.opengroup.org/unix/online.html .
  149. .PP
  150. Any typographical or formatting errors that appear
  151. in this page are most likely
  152. to have been introduced during the conversion of the source files to
  153. man page format. To report such errors, see
  154. https://www.kernel.org/doc/man-pages/reporting_bugs.html .