man3/posix_madvise.3

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