-<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. --><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="settinglustreproperties">
+<?xml version='1.0' encoding='UTF-8'?><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="settinglustreproperties">
<title xml:id="settinglustreproperties.title">Setting Lustre Properties in a C Program (<literal>llapi</literal>)</title>
<para>This chapter describes the <literal>llapi</literal> library of commands used for setting Lustre file properties within a C program running in a cluster environment, such as a data processing or MPI application. The commands described in this chapter are:</para>
<itemizedlist>
</section>
<section remap="h5">
<title>Description</title>
- <para>The <literal>llapi_file_create()</literal> function sets a file descriptor's Lustre striping information. The file descriptor is then accessed with <literal>open()</literal>.</para>
+ <para>The <literal>llapi_file_create()</literal> function sets a file descriptor's Lustre
+ file system striping information. The file descriptor is then accessed with
+ <literal>open()</literal>.</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<para> <literal>lmm_pattern</literal></para>
</entry>
<entry>
- <para>Holds the striping pattern. Only <literal>LOV_PATTERN_RAID0</literal> is possible in this Lustre version.</para>
+ <para>Holds the striping pattern. Only <literal>LOV_PATTERN_RAID0</literal> is
+ possible in this Lustre software release.</para>
</entry>
</row>
<row>
<title>
<literal>llapi_file_open</literal>
</title>
- <para>The <literal>llapi_file_open</literal> command opens (or creates) a file or device on a Lustre filesystem.</para>
+ <para>The <literal>llapi_file_open</literal> command opens (or creates) a file or device on a
+ Lustre file system.</para>
<section remap="h5">
<title>Synopsis</title>
<screen>#include <lustre/lustreapi.h>
<section remap="h5">
<title>Description</title>
<para>The <literal>llapi_file_create()</literal> call is equivalent to the <literal>llapi_file_open</literal> call with <emphasis>flags</emphasis> equal to <literal>O_CREAT|O_WRONLY</literal> and <emphasis>mode</emphasis> equal to <literal>0644</literal>, followed by file close.</para>
- <para><literal>llapi_file_open()</literal> opens a file with a given name on a Lustre filesystem.</para>
+ <para><literal>llapi_file_open()</literal> opens a file with a given name on a Lustre file
+ system.</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<para> <literal>stripe_pattern</literal></para>
</entry>
<entry>
- <para>Specifies the striping pattern. In this version of Lustre, only <literal>LOV_PATTERN_RAID0</literal> is available. The default value is 0.</para>
+ <para>Specifies the striping pattern. In this release of the Lustre software, only
+ <literal>LOV_PATTERN_RAID0</literal> is available. The default value is
+ 0.</para>
</entry>
</row>
</tbody>
<para> <literal>ENOTTY</literal></para>
</entry>
<entry>
- <para> <literal>name</literal> may not point to a Lustre filesystem.</para>
+ <para>
+ <literal>name</literal> may not point to a Lustre file system.</para>
</entry>
</row>
</tbody>
<para> <literal>LUSTRE_Q_QUOTAON</literal></para>
</entry>
<entry>
- <para>Turns on quotas for a Lustre file system. Deprecated as of 2.4.0. <emphasis>qc_type</emphasis> is <literal>USRQUOTA</literal>, <literal>GRPQUOTA</literal> or <literal>UGQUOTA</literal> (both user and group quota). The quota files must exist. They are normally created with the <literal>llapi_quotacheck</literal> call. This call is restricted to the super user privilege. As of 2.4.0, quota is now enabled on a per-filesystem basis via <literal>lctl conf_param</literal> (see <xref linkend="enabling_disk_quotas"/>) on the MGS node and quotacheck isn't needed any more.</para>
+ <para>Turns on quotas for a Lustre file system. Deprecated as of 2.4.0.
+ <emphasis>qc_type</emphasis> is <literal>USRQUOTA</literal>,
+ <literal>GRPQUOTA</literal> or <literal>UGQUOTA</literal> (both user and group
+ quota). The quota files must exist. They are normally created with the
+ <literal>llapi_quotacheck</literal> call. This call is restricted to the super
+ user privilege. As of 2.4.0, quota is now enabled on a per file system basis via
+ <literal>lctl conf_param</literal> (see <xref linkend="enabling_disk_quotas"/>)
+ on the MGS node and quotacheck isn't needed any more.</para>
</entry>
</row>
<row>
<para> <literal>LUSTRE_Q_GETINFO</literal></para>
</entry>
<entry>
- <para>Gets information about quotas. <emphasis>qc_type</emphasis> is either <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. On return, <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds), <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds), <emphasis>dqi_flags</emphasis> is not used by the current Lustre version.</para>
+ <para>Gets information about quotas. <emphasis>qc_type</emphasis> is either
+ <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. On return,
+ <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds),
+ <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds),
+ <emphasis>dqi_flags</emphasis> is not used by the current release of the Lustre
+ software.</para>
</entry>
</row>
<row>
<para> <literal>LUSTRE_Q_SETINFO</literal></para>
</entry>
<entry>
- <para>Sets quota information (like grace times). <emphasis>qc_type</emphasis> is either <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds), <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds), <emphasis>dqi_flags</emphasis> is not used by the current Lustre version and must be zeroed.</para>
+ <para>Sets quota information (like grace times). <emphasis>qc_type</emphasis> is
+ either <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>.
+ <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds),
+ <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds),
+ <emphasis>dqi_flags</emphasis> is not used by the current release of the Lustre
+ software and must be zeroed.</para>
</entry>
</row>
</tbody>
<para>non-zero value On failure</para>
</section>
</section>
+ <section condition="l29">
+ <title>
+ <literal>llapi_ladvise</literal>
+ </title>
+ <para>Use <literal>llapi_ladvise</literal> to give IO advice/hints on a
+ Lustre file to the server.</para>
+ <section remap="h5">
+ <title>Synopsis</title>
+ <screen>
+#include <lustre/lustreapi.h>
+int llapi_ladvise(int fd, unsigned long long flags,
+ int num_advise, struct llapi_lu_ladvise *ladvise);
+
+struct llapi_lu_ladvise {
+ __u16 lla_advice; /* advice type */
+ __u16 lla_value1; /* values for different advice types */
+ __u32 lla_value2;
+ __u64 lla_start; /* first byte of extent for advice */
+ __u64 lla_end; /* last byte of extent for advice */
+ __u32 lla_value3;
+ __u32 lla_value4;
+};
+ </screen>
+ </section>
+ <section remap="h5">
+ <title>Description</title>
+ <para>The <literal>llapi_ladvise</literal> function passes an array of
+ <emphasis>num_advise</emphasis> I/O hints (up to a maximum of
+ <emphasis>LAH_COUNT_MAX</emphasis> items) in ladvise for the file
+ descriptor <emphasis>fd</emphasis> from an application to one or more
+ Lustre servers. Optionally, <emphasis>flags</emphasis> can modify how
+ the advice will be processed via bitwise-or'd values:</para>
+ <itemizedlist><listitem>
+ <para><literal>LF_ASYNC</literal>: Clients return to userspace
+ immediately after submitting ladvise RPCs, leaving server threads to
+ handle the advices asynchronously.</para>
+ </listitem></itemizedlist>
+ <para>Each of the <emphasis>ladvise</emphasis> elements is an
+ <emphasis>llapi_lu_ladvise</emphasis> structure, which contains the
+ following fields:
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <thead>
+ <row>
+ <entry>
+ <para><emphasis role="bold">Field</emphasis></para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Description</emphasis></para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para> <literal>lla_ladvice</literal></para>
+ </entry>
+ <entry>
+ <para>Specifies the advice for the given file range, currently
+ one of:</para>
+ <para><literal>LU_LADVISE_WILLREAD</literal>: Prefetch data
+ into server cache using optimum I/O size for the server.</para>
+ <para><literal>LU_LADVISE_DONTNEED</literal>: Clean cached data
+ for the specified file range(s) on the server.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_start</literal></para>
+ </entry>
+ <entry>
+ <para>The offset in bytes for the start of this advice.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_end</literal></para>
+ </entry>
+ <entry>
+ <para>The offset in bytes (non-inclusive) for the end of this
+ advice.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_value1</literal></para>
+ <para> <literal>lla_value2</literal></para>
+ <para> <literal>lla_value3</literal></para>
+ <para> <literal>lla_value4</literal></para>
+ </entry>
+ <entry>
+ <para>Additional arguments for future advice types and
+ should be set to zero if not explicitly required for a given
+ advice type.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para><literal>llapi_ladvise()</literal> forwards the advice to Lustre
+ servers without guaranteeing how and when servers will react to the
+ advice. Actions may or may not be triggered when the advices are
+ received, depending on the type of the advice as well as the real-time
+ decision of the affected server-side components.
+ </para>
+ <para> A typical usage of <literal>llapi_ladvise()</literal> is to
+ enable applications and users (via <literal>lfs ladvise</literal>)
+ with external knowledge about application I/O patterns to intervene in
+ server-side I/O handling. For example, if a group of different clients
+ are doing small random reads of a file, prefetching pages into OSS
+ cache with big linear reads before the random IO is an overall net
+ benefit. Fetching that data into each client cache with
+ <emphasis>fadvise()</emphasis> may not be beneficial, due to much more
+ data being sent to the clients.
+ </para>
+ <para>While conceptually similar to the
+ <emphasis>posix_fadvise</emphasis> and Linux
+ <emphasis>fadvise</emphasis> system calls, the main difference of
+ <literal>llapi_ladvise()</literal> is that
+ <emphasis>fadvise() / posix_fadvise()</emphasis> are client side
+ mechanisms that do not pass advice to the filesystem, while
+ <literal>llapi_ladvise()</literal> sends advice or hints to one or
+ more Lustre servers on which the file is stored. In some cases it may
+ be desirable to use both interfaces.
+ </para>
+ </section>
+ <section remap="h5">
+ <title>Return Values</title>
+ <para><literal>llapi_ladvise</literal> returns:</para>
+ <para><literal>0</literal> On success</para>
+ <para><literal>-1</literal> if an error occurred (in which case, errno
+ is set appropriately).</para>
+ </section>
+ <section remap="h5">
+ <title>Errors</title>
+ <para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <thead>
+ <row>
+ <entry>
+ <para><emphasis role="bold">Error</emphasis></para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Description</emphasis></para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para> <literal>ENOMEM</literal></para>
+ </entry>
+ <entry>
+ <para>Insufficient memory to complete operation.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>EINVAL</literal></para>
+ </entry>
+ <entry>
+ <para>One or more invalid arguments are given.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>EFAULT</literal></para>
+ </entry>
+ <entry>
+ <para>Memory region pointed by
+ <literal>ladvise</literal> is not properly mapped.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>ENOTSUPP</literal></para>
+ </entry>
+ <entry>
+ <para>Advice type is not supported.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+ </section>
<section xml:id="dbdoclet.50438215_marker-1297700">
<title>Example Using the <literal>llapi</literal> Library</title>
- <para>Use <literal>llapi_file_create</literal> to set Lustre properties for a new file. For a synopsis and description of llapi_file_create and examples of how to use it, see <xref linkend="configurationfilesmoduleparameters"/>.</para>
+ <para>Use <literal>llapi_file_create</literal> to set Lustre software properties for a new file.
+ For a synopsis and description of <literal>llapi_file_create</literal> and examples of how to
+ use it, see <xref linkend="configurationfilesmoduleparameters"/>.</para>
<para>You can set striping from inside programs like <literal>ioctl</literal>. To compile the sample program, you need to install the Lustre client source RPM.</para>
<para><emphasis role="bold">A simple C program to demonstrate striping API - libtest.c</emphasis></para>
<programlisting>
git://git.whamcloud.com / doc / manual.git / blobdiff