man2/msync.2

   1 .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH msync 2 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 msync \- synchronize a file with a memory map
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <sys/mman.h>
  14 .P
  15 .BI "int msync(void " addr [. length "], size_t " length ", int " flags );
  16 .fi
  17 .SH DESCRIPTION
  18 .BR msync ()
  19 flushes changes made to the in-core copy of a file that was mapped
  20 into memory using
  21 .BR mmap (2)
  22 back to the filesystem.
  23 Without use of this call,
  24 there is no guarantee that changes are written back before
  25 .BR munmap (2)
  26 is called.
  27 To be more precise, the part of the file that
  28 corresponds to the memory area starting at
  29 .I addr
  30 and having length
  31 .I length
  32 is updated.
  33 .P
  34 The
  35 .I flags
  36 argument should specify exactly one of
  37 .B MS_ASYNC
  38 and
  39 .BR MS_SYNC ,
  40 and may additionally include the
  41 .B MS_INVALIDATE
  42 bit.
  43 These bits have the following meanings:
  44 .TP
  45 .B MS_ASYNC
  46 Specifies that an update be scheduled, but the call returns immediately.
  47 .TP
  48 .B MS_SYNC
  49 Requests an update and waits for it to complete.
  50 .TP
  51 .B MS_INVALIDATE
  52 .\" Since Linux 2.4, this seems to be a no-op (other than the
  53 .\" EBUSY check for VM_LOCKED).
  54 Asks to invalidate other mappings of the same file
  55 (so that they can be updated with the fresh values just written).
  56 .SH RETURN VALUE
  57 On success, zero is returned.
  58 On error, \-1 is returned, and
  59 .I errno
  60 is set to indicate the error.
  61 .SH ERRORS
  62 .TP
  63 .B EBUSY
  64 .B MS_INVALIDATE
  65 was specified in
  66 .IR flags ,
  67 and a memory lock exists for the specified address range.
  68 .TP
  69 .B EINVAL
  70 .I addr
  71 is not a multiple of PAGESIZE; or any bit other than
  72 .BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC
  73 is set in
  74 .IR flags ;
  75 or both
  76 .B MS_SYNC
  77 and
  78 .B MS_ASYNC
  79 are set in
  80 .IR flags .
  81 .TP
  82 .B ENOMEM
  83 The indicated memory (or part of it) was not mapped.
  84 .SH VERSIONS
  85 According to POSIX, either
  86 .B MS_SYNC
  87 or
  88 .B MS_ASYNC
  89 must be specified in
  90 .IR flags ,
  91 and indeed failure to include one of these flags will cause
  92 .BR msync ()
  93 to fail on some systems.
  94 However, Linux permits a call to
  95 .BR msync ()
  96 that specifies neither of these flags,
  97 with semantics that are (currently) equivalent to specifying
  98 .BR MS_ASYNC .
  99 (Since Linux 2.6.19,
 100 .\" commit 204ec841fbea3e5138168edbc3a76d46747cc987
 101 .B MS_ASYNC
 102 is in fact a no-op, since the kernel properly tracks dirty
 103 pages and flushes them to storage as necessary.)
 104 Notwithstanding the Linux behavior,
 105 portable, future-proof applications should ensure that they specify either
 106 .B MS_SYNC
 107 or
 108 .B MS_ASYNC
 109 in
 110 .IR flags .
 111 .SH STANDARDS
 112 POSIX.1-2008.
 113 .SH HISTORY
 114 POSIX.1-2001.
 115 .P
 116 This call was introduced in Linux 1.3.21, and then used
 117 .B EFAULT
 118 instead of
 119 .BR ENOMEM .
 120 In Linux 2.4.19, this was changed to the POSIX value
 121 .BR ENOMEM .
 122 .P
 123 On POSIX systems on which
 124 .BR msync ()
 125 is available, both
 126 .B _POSIX_MAPPED_FILES
 127 and
 128 .B _POSIX_SYNCHRONIZED_IO
 129 are defined in
 130 .I <unistd.h>
 131 to a value greater than 0.
 132 (See also
 133 .BR sysconf (3).)
 134 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 135 .\" -1: unavailable, 0: ask using sysconf().
 136 .\" glibc defines them to 1.
 137 .SH SEE ALSO
 138 .BR mmap (2)
 139 .P
 140 B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391.