<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sd_readahead" conditional='ENABLE_READAHEAD'>

<refentryinfo>

<title>sd_readahead</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_readahead</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_readahead</refname>

<refpurpose>Control ongoing disk boot-time read-ahead operations</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include "sd-readahead.h"</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_readahead</function></funcdef>

<paramdef>const char *<parameter>action</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_readahead()</function> may be

called by programs involved with early boot-up to

control ongoing boot-time disk read-ahead operations. It may be

used to terminate read-ahead operations in case an

uncommon disk access pattern is to be expected and

hence read-ahead replay or collection is unlikely to

have the desired speed-up effect on the current or

future boot-ups.</para>

<para>The <parameter>action</parameter> should be one

of the following strings:</para>

<variablelist>

<varlistentry>

<term>cancel</term>

<listitem><para>Terminates read-ahead

data collection, and drops all

read-ahead data collected during this

boot-up.</para></listitem>

</varlistentry>

<varlistentry>

<term>done</term>

<listitem><para>Terminates read-ahead

data collection, but keeps all

read-ahead data collected during this

boot-up around for use during

subsequent boot-ups.</para></listitem>

</varlistentry>

<varlistentry>

<term>noreplay</term>

<listitem><para>Terminates read-ahead

replay.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On failure, these calls return a negative

errno-style error code. It is generally recommended to

ignore the return value of this call.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>This function is provided by the reference

implementation of APIs for controlling boot-time

read-ahead and distributed with the systemd

package. The algorithm it implements is simple, and

can easily be reimplemented in daemons if it is

important to support this interface without using the

reference implementation.</para>

<para>Internally, this function creates a file in

<filename>/run/systemd/readahead/</filename> which is

then used as flag file to notify the read-ahead

subsystem.</para>

<para>For details about the algorithm check the

liberally licensed reference implementation sources:

<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/readahead/sd-readahead.c"/>

and <ulink

url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-readahead.h"/></para>

<para><function>sd_readahead()</function> is

implemented in the reference implementation's drop-in

<filename>sd-readahead.c</filename> and

<filename>sd-readahead.h</filename> files. It is

recommended that applications consuming this API copy

the implementation into their source tree. For more

details about the reference implementation see

<citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>

<para>If -DDISABLE_SYSTEMD is set during compilation,

this function will always return 0 and otherwise

become a NOP.</para>

</refsect1>

<refsect1>

<title>Examples</title>

<example>

<title>Cancelling all read-ahead operations</title>

<para>During boots where SELinux has to

relabel the file system hierarchy, it will

create a large amount of disk accesses that

are not necessary during normal boots. Hence

it is a good idea to disable both read-ahead replay and read-ahead collection.

</para>

<programlisting>sd_readahead("cancel");

sd_readahead("noreplay");</programlisting>

</example>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>