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 2021-03-22 "Linux" "Linux Programmer's Manual"
   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 .PP
  15 .BI "int msync(void *" addr ", 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 .PP
  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 CONFORMING TO
  85 POSIX.1-2001, POSIX.1-2008.
  86 .PP
  87 This call was introduced in Linux 1.3.21, and then used
  88 .B EFAULT
  89 instead of
  90 .BR ENOMEM .
  91 In Linux 2.4.19, this was changed to the POSIX value
  92 .BR ENOMEM .
  93 .PP
  94 On POSIX systems on which
  95 .BR msync ()
  96 is available, both
  97 .B _POSIX_MAPPED_FILES
  98 and
  99 .B _POSIX_SYNCHRONIZED_IO
 100 are defined in
 101 .I <unistd.h>
 102 to a value greater than 0.
 103 (See also
 104 .BR sysconf (3).)
 105 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 106 .\" -1: unavailable, 0: ask using sysconf().
 107 .\" glibc defines them to 1.
 108 .SH NOTES
 109 According to POSIX, either
 110 .B MS_SYNC
 111 or
 112 .B MS_ASYNC
 113 must be specified in
 114 .IR flags ,
 115 and indeed failure to include one of these flags will cause
 116 .BR msync ()
 117 to fail on some systems.
 118 However, Linux permits a call to
 119 .BR msync ()
 120 that specifies neither of these flags,
 121 with semantics that are (currently) equivalent to specifying
 122 .BR MS_ASYNC .
 123 (Since Linux 2.6.19,
 124 .\" commit 204ec841fbea3e5138168edbc3a76d46747cc987
 125 .B MS_ASYNC
 126 is in fact a no-op, since the kernel properly tracks dirty
 127 pages and flushes them to storage as necessary.)
 128 Notwithstanding the Linux behavior,
 129 portable, future-proof applications should ensure that they specify either
 130 .B MS_SYNC
 131 or
 132 .B MS_ASYNC
 133 in
 134 .IR flags .
 135 .SH SEE ALSO
 136 .BR mmap (2)
 137 .PP
 138 B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391.