man/sd_readahead.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_notify">
  25
  26         <refentryinfo>
  27                 <title>sd_readahead</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>sd_readahead</refentrytitle>
  42                 <manvolnum>3</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>sd_readahead</refname>
  47                 <refpurpose>Control ongoing disk boot-time read-ahead operations</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <funcsynopsis>
  52                         <funcsynopsisinfo>#include "sd-readahead.h"</funcsynopsisinfo>
  53
  54                         <funcprototype>
  55                                 <funcdef>int <function>sd_readahead</function></funcdef>
  56                                 <paramdef>const char *<parameter>action</parameter></paramdef>
  57                         </funcprototype>
  58                 </funcsynopsis>
  59         </refsynopsisdiv>
  60
  61         <refsect1>
  62                 <title>Description</title>
  63                 <para><function>sd_readahead()</function> may be
  64                 called by programs involved with early boot-up to
  65                 control ongoing boot-time disk read-ahead operations. It may be
  66                 used to terminate read-ahead operations in case an
  67                 uncommon disk access pattern is to be expected and
  68                 hence read-ahead replay or collection is unlikely to
  69                 have the desired speed-up effect on the current or
  70                 future boot-ups.</para>
  71
  72                 <para>The <parameter>action</parameter> should be one
  73                 of the following strings:</para>
  74
  75                 <variablelist>
  76                         <varlistentry>
  77                                 <term>cancel</term>
  78
  79                                 <listitem><para>Terminates read-ahead
  80                                 data collection, and drops all
  81                                 read-ahead data collected during this
  82                                 boot-up.</para></listitem>
  83                         </varlistentry>
  84
  85                         <varlistentry>
  86                                 <term>done</term>
  87
  88                                 <listitem><para>Terminates read-ahead
  89                                 data collection, but keeps all
  90                                 read-ahead data collected during this
  91                                 boot-up around for use during
  92                                 subsequent boot-ups.</para></listitem>
  93                         </varlistentry>
  94
  95                         <varlistentry>
  96                                 <term>noreplay</term>
  97
  98                                 <listitem><para>Terminates read-ahead
  99                                 replay.</para></listitem>
 100                         </varlistentry>
 101
 102                 </variablelist>
 103
 104         </refsect1>
 105
 106         <refsect1>
 107                 <title>Return Value</title>
 108
 109                 <para>On failure, these calls return a negative
 110                 errno-style error code. It is generally recommended to
 111                 ignore the return value of this call.</para>
 112         </refsect1>
 113
 114         <refsect1>
 115                 <title>Notes</title>
 116
 117                 <para>This function is provided by the reference
 118                 implementation of APIs for controlling boot-time
 119                 read-ahead and distributed with the systemd
 120                 package. The algorithm it implements is simple, and
 121                 can easily be reimplemented in daemons if it is
 122                 important to support this interface without using the
 123                 reference implementation.</para>
 124
 125                 <para>Internally, this function creates a file in
 126                 <filename>/run/systemd/readahead/</filename> which is
 127                 then used as flag file to notify the read-ahead
 128                 subsystem.</para>
 129
 130                 <para>For details about the algorithm check the
 131                 liberally licensed reference implementation sources:
 132                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/readahead/sd-readahead.c"/>
 133                 resp. <ulink
 134                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-readahead.h"/></para>
 135
 136                 <para><function>sd_readahead()</function> is
 137                 implemented in the reference implementation's drop-in
 138                 <filename>sd-readahead.c</filename> and
 139                 <filename>sd-readahead.h</filename> files. It is
 140                 recommended that applications consuming this API copy
 141                 the implementation into their source tree. For more
 142                 details about the reference implementation see
 143                 <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
 144
 145                 <para>If -DDISABLE_SYSTEMD is set during compilation
 146                 this function will always return 0 and otherwise
 147                 become a NOP.</para>
 148         </refsect1>
 149
 150         <refsect1>
 151                 <title>Examples</title>
 152
 153                 <example>
 154                         <title>Cancelling all read-ahead operations</title>
 155
 156                         <para>During boots where SELinux has to
 157                         relabel the file system hierarchy, it will
 158                         create a large amount of disk accesses that
 159                         are not necessary during normal boots. Hence
 160                         it is a good idea to disable both read-ahead replay and read-ahead collection.
 161                         </para>
 162
 163                         <programlisting>sd_readahead("cancel");
 164 sd_readahead("noreplay");</programlisting>
 165                 </example>
 166
 167         </refsect1>
 168
 169         <refsect1>
 170                 <title>See Also</title>
 171                 <para>
 172                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 173                         <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 174                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 175                 </para>
 176         </refsect1>
 177
 178 </refentry>