gl/lib/fadvise.h

   1 /* Declare an access pattern hint for files.
   2    Copyright (C) 2010-2011 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  16
  17 #include <config.h>
  18 #include <stdio.h>
  19 #include <fcntl.h>
  20 #include <sys/types.h>
  21
  22 /* There are a few hints one can provide, which have the
  23    following characteristics on Linux 2.6.31 at least.
  24
  25    POSIX_FADV_SEQUENTIAL
  26      Doubles the size of read ahead done for file
  27    POSIX_FADV_WILLNEED
  28      _synchronously_ prepopulate the buffer cache with the file
  29    POSIX_FADV_NOREUSE
  30      Could lower priority of data in buffer caches,
  31      but currently does nothing.
  32    POSIX_FADV_DONTNEED
  33      Drop the file from cache.
  34      Note this is automatically done when files are unlinked.
  35
  36    We use this enum "type" both to make it explicit that
  37    these options are mutually exclusive, and to discourage
  38    the passing of the possibly undefined POSIX_FADV_... values.
  39    Note we could #undef the POSIX_FADV_ values, but that would
  40    preclude using the posix_fadvise() function with its standard
  41    constants. Using posix_fadvise() might be required if the return
  42    value is needed, but it must be guarded by appropriate #ifdefs.  */
  43
  44 #if HAVE_POSIX_FADVISE
  45 typedef enum {
  46   FADVISE_NORMAL =     POSIX_FADV_NORMAL,
  47   FADVISE_SEQUENTIAL = POSIX_FADV_SEQUENTIAL,
  48   FADVISE_NOREUSE =    POSIX_FADV_NOREUSE,
  49   FADVISE_DONTNEED =   POSIX_FADV_DONTNEED,
  50   FADVISE_WILLNEED =   POSIX_FADV_WILLNEED,
  51   FADVISE_RANDOM =     POSIX_FADV_RANDOM,
  52 } fadvice_t;
  53 #else
  54 typedef enum {
  55   FADVISE_NORMAL,
  56   FADVISE_SEQUENTIAL,
  57   FADVISE_NOREUSE,
  58   FADVISE_DONTNEED,
  59   FADVISE_WILLNEED,
  60   FADVISE_RANDOM,
  61 } fadvice_t;
  62 #endif
  63
  64 /* We ignore any errors as these hints are only advisory.
  65    There is the chance one can pass invalid ADVICE, which will
  66    not be indicated, but given the simplicity of the interface
  67    this is unlikely.  Also not returning errors allows the
  68    unconditional passing of descriptors to non standard files,
  69    which will just be ignored if unsupported.  */
  70
  71 void fdadvise (int fd, off_t offset, off_t len, fadvice_t advice);
  72 void fadvise (FILE *fp, fadvice_t advice);