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

msync.3p (5773B)


  1. '\" et
  2. .TH MSYNC "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. msync
  12. \(em synchronize memory with physical storage
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/mman.h>
  17. .P
  18. int msync(void *\fIaddr\fP, size_t \fIlen\fP, int \fIflags\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fImsync\fR()
  23. function shall write all modified data to permanent storage locations,
  24. if any, in those whole pages containing any part of the address space of
  25. the process starting at address
  26. .IR addr
  27. and continuing for
  28. .IR len
  29. bytes. If no such storage exists,
  30. \fImsync\fR()
  31. need not have any effect. If requested, the
  32. \fImsync\fR()
  33. function shall then invalidate cached copies of data.
  34. .P
  35. The implementation may require that
  36. .IR addr
  37. be a multiple of the page size as returned by
  38. \fIsysconf\fR().
  39. .P
  40. For mappings to files, the
  41. \fImsync\fR()
  42. function shall ensure that all write operations are completed as
  43. defined for synchronized I/O data integrity completion. It is
  44. unspecified whether the implementation also writes out other file
  45. attributes. When the
  46. \fImsync\fR()
  47. function is called on MAP_PRIVATE mappings, any modified data shall
  48. not be written to the underlying object and shall not cause such data
  49. to be made visible to other processes. It is unspecified whether data
  50. in MAP_PRIVATE mappings has any permanent storage locations.
  51. The effect of
  52. \fImsync\fR()
  53. on a shared memory object or a typed memory object is unspecified.
  54. The behavior of this function is unspecified if the mapping was not
  55. established by a call to
  56. \fImmap\fR().
  57. .P
  58. The
  59. .IR flags
  60. argument is constructed from the bitwise-inclusive OR of one or more of
  61. the following flags defined in the
  62. .IR <sys/mman.h>
  63. header:
  64. .TS
  65. center box tab(!);
  66. cB | cB
  67. lw(1.5i) | lw(2i).
  68. Symbolic Constant!Description
  69. _
  70. MS_ASYNC!Perform asynchronous writes.
  71. MS_SYNC!Perform synchronous writes.
  72. MS_INVALIDATE!Invalidate cached data.
  73. .TE
  74. .P
  75. When MS_ASYNC is specified,
  76. \fImsync\fR()
  77. shall return immediately once all the write operations are initiated or
  78. queued for servicing; when MS_SYNC is specified,
  79. \fImsync\fR()
  80. shall not return until all write operations are completed as defined for
  81. synchronized I/O data integrity completion. Either MS_ASYNC or MS_SYNC
  82. shall be specified, but not both.
  83. .P
  84. When MS_INVALIDATE is specified,
  85. \fImsync\fR()
  86. shall invalidate all cached copies of mapped data that are inconsistent
  87. with the permanent storage locations such that subsequent references
  88. shall obtain data that was consistent with the permanent storage
  89. locations sometime between the call to
  90. \fImsync\fR()
  91. and the first subsequent memory reference to the data.
  92. .P
  93. If
  94. \fImsync\fR()
  95. causes any write to a file, the file's last data modification and
  96. last file status change timestamps shall be marked for update.
  97. .SH "RETURN VALUE"
  98. Upon successful completion,
  99. \fImsync\fR()
  100. shall return 0; otherwise, it shall return \-1 and set
  101. .IR errno
  102. to indicate the error.
  103. .SH ERRORS
  104. The
  105. \fImsync\fR()
  106. function shall fail if:
  107. .TP
  108. .BR EBUSY
  109. Some or all of the addresses in the range starting at
  110. .IR addr
  111. and continuing for
  112. .IR len
  113. bytes are locked, and MS_INVALIDATE is specified.
  114. .TP
  115. .BR EINVAL
  116. The value of
  117. .IR flags
  118. is invalid.
  119. .TP
  120. .BR ENOMEM
  121. The addresses in the range starting at
  122. .IR addr
  123. and continuing for
  124. .IR len
  125. bytes are outside the range allowed for the address space of a process
  126. or specify one or more pages that are not mapped.
  127. .P
  128. The
  129. \fImsync\fR()
  130. function may fail if:
  131. .TP
  132. .BR EINVAL
  133. The value of
  134. .IR addr
  135. is not a multiple of the page size as returned by
  136. \fIsysconf\fR().
  137. .LP
  138. .IR "The following sections are informative."
  139. .SH EXAMPLES
  140. None.
  141. .SH "APPLICATION USAGE"
  142. The
  143. \fImsync\fR()
  144. function is only supported if the Synchronized Input and Output
  145. option is supported, and thus need not be available on all implementations.
  146. .P
  147. The
  148. \fImsync\fR()
  149. function should be used by programs that require a memory object to be
  150. in a known state; for example, in building transaction facilities.
  151. .P
  152. Normal system activity can cause pages to be written to disk.
  153. Therefore, there are no guarantees that
  154. \fImsync\fR()
  155. is the only control over when pages are or are not written to disk.
  156. .SH RATIONALE
  157. The
  158. \fImsync\fR()
  159. function writes out data in a mapped region to the permanent
  160. storage for the underlying object. The call to
  161. \fImsync\fR()
  162. ensures data integrity of the file.
  163. .P
  164. After the data is written out, any cached data may be invalidated if
  165. the MS_INVALIDATE
  166. flag was specified. This is useful on systems that do not support
  167. read/write consistency.
  168. .SH "FUTURE DIRECTIONS"
  169. None.
  170. .SH "SEE ALSO"
  171. .IR "\fImmap\fR\^(\|)",
  172. .IR "\fIsysconf\fR\^(\|)"
  173. .P
  174. The Base Definitions volume of POSIX.1\(hy2017,
  175. .IR "\fB<sys_mman.h>\fP"
  176. .\"
  177. .SH COPYRIGHT
  178. Portions of this text are reprinted and reproduced in electronic form
  179. from IEEE Std 1003.1-2017, Standard for Information Technology
  180. -- Portable Operating System Interface (POSIX), The Open Group Base
  181. Specifications Issue 7, 2018 Edition,
  182. Copyright (C) 2018 by the Institute of
  183. Electrical and Electronics Engineers, Inc and The Open Group.
  184. In the event of any discrepancy between this version and the original IEEE and
  185. The Open Group Standard, the original IEEE and The Open Group Standard
  186. is the referee document. The original Standard can be obtained online at
  187. http://www.opengroup.org/unix/online.html .
  188. .PP
  189. Any typographical or formatting errors that appear
  190. in this page are most likely
  191. to have been introduced during the conversion of the source files to
  192. man page format. To report such errors, see
  193. https://www.kernel.org/doc/man-pages/reporting_bugs.html .