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 General Public License as published by
  12   the Free Software Foundation; either version 2 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   General Public License for more details.
  19
  20   You should have received a copy of the GNU 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-daemon.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/tree/src/sd-readahead.c"/>
 133                 resp. <ulink
 134                 url="http://cgit.freedesktop.org/systemd/tree/src/sd-readahead.h"/></para>
 135
 136                 <para><function>sd_readahead()</function> is
 137                 implemented in the reference implementation's
 138                 <filename>sd-readahead.c</filename> and
 139                 <filename>sd-readahead.h</filename> files. These
 140                 interfaces are available as shared library, which can
 141                 be compiled and linked to with the
 142                 <literal>libsystemd-daemon</literal>
 143                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 144                 file. Alternatively, applications consuming this API
 145                 may copy the implementation into their source
 146                 tree. For more details about the reference
 147                 implementation see
 148                 <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 149
 150                 <para>If the reference implementation is used as
 151                 drop-in files and -DDISABLE_SYSTEMD is set during
 152                 compilation this function will always return 0 and
 153                 otherwise become a NOP.</para>
 154         </refsect1>
 155
 156         <refsect1>
 157                 <title>Examples</title>
 158
 159                 <example>
 160                         <title>Cancelling all read-ahead operations</title>
 161
 162                         <para>During boots where SELinux has to
 163                         relabel the file system hierarchy, it will
 164                         create a large amount of disk accesses that
 165                         are not necessary during normal boots. Hence
 166                         it is a good idea to disable both read-ahead replay and read-ahead collection.
 167                         </para>
 168
 169                         <programlisting>sd_readahead("cancel");
 170 sd_readahead("noreplay");</programlisting>
 171                 </example>
 172
 173         </refsect1>
 174
 175         <refsect1>
 176                 <title>See Also</title>
 177                 <para>
 178                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 179                         <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 180                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 181                 </para>
 182         </refsect1>
 183
 184 </refentry>