man3/posix_madvise.3

   1 .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+)
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or modify
   6 .\" it under the terms of the GNU General Public License as published by
   7 .\" the Free Software Foundation; either version 2 of the License, or
   8 .\" (at your option) any later version.
   9 .\"
  10 .\" This program is distributed in the hope that it will be useful,
  11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 .\" GNU General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public
  16 .\" License along with this manual; if not, see
  17 .\" <http://www.gnu.org/licenses/>.
  18 .\" %%%LICENSE_END
  19 .\"
  20 .TH POSIX_MADVISE 3 2017-09-15 Linux "Linux Programmer's Manual"
  21 .SH NAME
  22 posix_madvise \- give advice about patterns of memory usage
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <sys/mman.h>
  26 .PP
  27 .BI "int posix_madvise(void *" addr ", size_t " len ", int " advice );
  28 .fi
  29 .PP
  30 .in -4n
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .in
  34 .PP
  35 .BR posix_madvise ():
  36 .br
  37 .RS 4
  38 .ad l
  39 _POSIX_C_SOURCE >= 200112L
  40 .RE
  41 .ad
  42 .SH DESCRIPTION
  43 The
  44 .BR posix_madvise ()
  45 function allows an application to advise the system about its expected
  46 patterns of usage of memory in the address range starting at
  47 .I addr
  48 and continuing for
  49 .I len
  50 bytes.
  51 The system is free to use this advice in order to improve the performance
  52 of memory accesses (or to ignore the advice altogether), but calling
  53 .BR posix_madvise ()
  54 shall not affect the semantics of access to memory in the specified range.
  55 .PP
  56 The
  57 .I advice
  58 argument is one of the following:
  59 .TP
  60 .B POSIX_MADV_NORMAL
  61 The application has no special advice regarding its memory usage patterns
  62 for the specified address range.
  63 This is the default behavior.
  64 .TP
  65 .B POSIX_MADV_SEQUENTIAL
  66 The application expects to access the specified address range sequentially,
  67 running from lower addresses to higher addresses.
  68 Hence, pages in this region can be aggressively read ahead,
  69 and may be freed soon after they are accessed.
  70 .TP
  71 .B POSIX_MADV_RANDOM
  72 The application expects to access the specified address range randomly.
  73 Thus, read ahead may be less useful than normally.
  74 .TP
  75 .B POSIX_MADV_WILLNEED
  76 The application expects to access the specified address range
  77 in the near future.
  78 Thus, read ahead may be beneficial.
  79 .TP
  80 .B POSIX_MADV_DONTNEED
  81 The application expects that it will not access the specified address range
  82 in the near future.
  83 .SH RETURN VALUE
  84 On success,
  85 .BR posix_madvise ()
  86 returns 0.
  87 On failure, it returns a positive error number.
  88 .SH ERRORS
  89 .TP
  90 .B EINVAL
  91 .I addr
  92 is not a multiple of the system page size or
  93 .I len
  94 is negative.
  95 .TP
  96 .B EINVAL
  97 .I advice
  98 is invalid.
  99 .TP
 100 .B ENOMEM
 101 Addresses in the specified range are partially or completely outside
 102 the caller's address space.
 103 .SH VERSIONS
 104 Support for
 105 .BR posix_madvise ()
 106 first appeared in glibc version 2.2.
 107 .SH CONFORMING TO
 108 POSIX.1-2001.
 109 .SH NOTES
 110 POSIX.1 permits an implementation to generate an error if
 111 .I len
 112 is 0.
 113 On Linux, specifying
 114 .I len
 115 as 0 is permitted (as a successful no-op).
 116 .PP
 117 In glibc, this function is implemented using
 118 .BR madvise (2).
 119 However, since glibc 2.6,
 120 .BR POSIX_MADV_DONTNEED
 121 is treated as a no-op, because the corresponding
 122 .BR madvise (2)
 123 value,
 124 .BR MADV_DONTNEED ,
 125 has destructive semantics.
 126 .SH SEE ALSO
 127 .BR madvise (2),
 128 .BR posix_fadvise (2)