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 2021-03-22 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 .RS -4
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .RE
  34 .PP
  35 .BR posix_madvise ():
  36 .nf
  37     _POSIX_C_SOURCE >= 200112L
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR posix_madvise ()
  42 function allows an application to advise the system about its expected
  43 patterns of usage of memory in the address range starting at
  44 .I addr
  45 and continuing for
  46 .I len
  47 bytes.
  48 The system is free to use this advice in order to improve the performance
  49 of memory accesses (or to ignore the advice altogether), but calling
  50 .BR posix_madvise ()
  51 shall not affect the semantics of access to memory in the specified range.
  52 .PP
  53 The
  54 .I advice
  55 argument is one of the following:
  56 .TP
  57 .B POSIX_MADV_NORMAL
  58 The application has no special advice regarding its memory usage patterns
  59 for the specified address range.
  60 This is the default behavior.
  61 .TP
  62 .B POSIX_MADV_SEQUENTIAL
  63 The application expects to access the specified address range sequentially,
  64 running from lower addresses to higher addresses.
  65 Hence, pages in this region can be aggressively read ahead,
  66 and may be freed soon after they are accessed.
  67 .TP
  68 .B POSIX_MADV_RANDOM
  69 The application expects to access the specified address range randomly.
  70 Thus, read ahead may be less useful than normally.
  71 .TP
  72 .B POSIX_MADV_WILLNEED
  73 The application expects to access the specified address range
  74 in the near future.
  75 Thus, read ahead may be beneficial.
  76 .TP
  77 .B POSIX_MADV_DONTNEED
  78 The application expects that it will not access the specified address range
  79 in the near future.
  80 .SH RETURN VALUE
  81 On success,
  82 .BR posix_madvise ()
  83 returns 0.
  84 On failure, it returns a positive error number.
  85 .SH ERRORS
  86 .TP
  87 .B EINVAL
  88 .I addr
  89 is not a multiple of the system page size or
  90 .I len
  91 is negative.
  92 .TP
  93 .B EINVAL
  94 .I advice
  95 is invalid.
  96 .TP
  97 .B ENOMEM
  98 Addresses in the specified range are partially or completely outside
  99 the caller's address space.
 100 .SH VERSIONS
 101 Support for
 102 .BR posix_madvise ()
 103 first appeared in glibc version 2.2.
 104 .SH CONFORMING TO
 105 POSIX.1-2001.
 106 .SH NOTES
 107 POSIX.1 permits an implementation to generate an error if
 108 .I len
 109 is 0.
 110 On Linux, specifying
 111 .I len
 112 as 0 is permitted (as a successful no-op).
 113 .PP
 114 In glibc, this function is implemented using
 115 .BR madvise (2).
 116 However, since glibc 2.6,
 117 .BR POSIX_MADV_DONTNEED
 118 is treated as a no-op, because the corresponding
 119 .BR madvise (2)
 120 value,
 121 .BR MADV_DONTNEED ,
 122 has destructive semantics.
 123 .SH SEE ALSO
 124 .BR madvise (2),
 125 .BR posix_fadvise (2)