-<?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">
+<?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>
<listitem>
- <para><xref linkend="dbdoclet.50438215_30970"/></para>
+ <para><xref linkend="llapi_file_create"/></para>
</listitem>
<listitem>
- <para><xref linkend="dbdoclet.50438215_50149"/></para>
+ <para><xref linkend="llapi_file_get_stripe"/></para>
</listitem>
<listitem>
- <para><xref linkend="dbdoclet.50438215_86607"/></para>
+ <para><xref linkend="llapi_file_open"/></para>
</listitem>
<listitem>
- <para><xref linkend="dbdoclet.50438215_12433"/></para>
+ <para><xref linkend="llapi_quotactl"/></para>
</listitem>
<listitem>
- <para><xref linkend="dbdoclet.50438215_15718"/></para>
+ <para><xref linkend="llapi_path2fid"/></para>
</listitem>
</itemizedlist>
<note>
<para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
</note>
- <section xml:id="dbdoclet.50438215_30970">
+ <section xml:id="llapi_file_create">
<title>
<literal>llapi_file_create</literal>
</title>
}</screen>
</section>
</section>
- <section xml:id="dbdoclet.50438215_50149">
+ <section xml:id="llapi_file_get_stripe">
<title>llapi_file_get_stripe</title>
<para>Use <literal>llapi_file_get_stripe</literal> to get striping information for a file or directory on a Lustre file system.</para>
<section remap="h5">
</programlisting>
</section>
</section>
- <section xml:id="dbdoclet.50438215_86607">
+ <section xml:id="llapi_file_open">
<title>
<literal>llapi_file_open</literal>
</title>
</programlisting>
</section>
</section>
- <section xml:id="dbdoclet.50438215_12433">
+ <section xml:id="llapi_quotactl">
<title>
<literal>llapi_quotactl</literal>
</title>
<tbody>
<row>
<entry>
- <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 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>
- <entry>
- <para> <literal>LUSTRE_Q_QUOTAOFF</literal></para>
- </entry>
- <entry>
- <para>Turns off 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). This call is restricted to the super user privilege. As of 2.4.0, quota is disabled via <literal>lctl conf_param</literal> (see <xref linkend="enabling_disk_quotas"/>).</para>
- </entry>
- </row>
- <row>
- <entry>
<para> <literal>LUSTRE_Q_GETQUOTA</literal></para>
</entry>
<entry>
</row>
<row>
<entry>
- <para> <literal>EBUSY</literal></para>
- </entry>
- <entry>
- <para>Cannot process during quotacheck.</para>
- </entry>
- </row>
- <row>
- <entry>
<para> <literal>ENOENT</literal></para>
</entry>
<entry>
</informaltable>
</section>
</section>
- <section xml:id="dbdoclet.50438215_15718">
+ <section xml:id="llapi_path2fid">
<title>
<literal>llapi_path2fid</literal>
</title>
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
+ <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>
+ </listitem>
+ <listitem>
+ <para><literal>LF_UNSET</literal>: Unset/clear a previous advice
+ (Currently only supports LU_ADVISE_LOCKNOEXPAND).</para>
+ </listitem>
+ </itemizedlist>
<para>Each of the <emphasis>ladvise</emphasis> elements is an
<emphasis>llapi_lu_ladvise</emphasis> structure, which contains the
following fields:
<entry>
<para>Additional arguments for future advice types and
should be set to zero if not explicitly required for a given
- advice type.</para>
+ advice type. Advice-specific names for these fields
+ follow.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_lockahead_mode</literal></para>
+ </entry>
+ <entry>
+ <para>When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field
+ is used to communicate the requested lock mode, and can be
+ referred to as lla_lockahead_mode.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_peradvice_flags</literal></para>
+ </entry>
+ <entry>
+ <para>When using advices which support them, the 'lla_value2'
+ field is used to communicate per-advice flags and can be
+ referred to as 'lla_peradvice_flags'. Both LF_ASYNC and
+ LF_UNSET are supported as peradvice flags.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> <literal>lla_lockahead_result</literal></para>
+ </entry>
+ <entry>
+ <para>When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field
+ is used to communicate the result of the request, and can be
+ referred to as lla_lockahead_result.</para>
</entry>
</row>
</tbody>
<emphasis>fadvise()</emphasis> may not be beneficial, due to much more
data being sent to the clients.
</para>
+ <para>
+ LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible
+ and encouraged to use it directly in your application to avoid lock
+ contention (primarily for writing to a single file from multiple
+ clients), it will also be available in the MPI-I/O / MPICH library
+ from ANL for use with the i/o aggregation mode of that library. This
+ is intended (eventually) to be the primary way this feature is used.
+ </para>
+ <para>
+ At the time of writing, this support is proposed as a patch but is
+ not yet merged in to the public ANL code base. Users are encouraged
+ to check their MPICH documentation and/or check with their library
+ provider about support.
+ </para>
<para>While conceptually similar to the
<emphasis>posix_fadvise</emphasis> and Linux
<emphasis>fadvise</emphasis> system calls, the main difference of
</para>
</section>
</section>
- <section xml:id="dbdoclet.50438215_marker-1297700">
+ <section xml:id="example_using_llapi">
<title>Example Using the <literal>llapi</literal> Library</title>
<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
<itemizedlist>
<listitem>
<para>
- <xref linkend="dbdoclet.50438215_30970"/>
+ <xref linkend="llapi_file_create"/>
</para>
</listitem>
<listitem>
<para>
- <xref linkend="dbdoclet.50438215_50149"/>
+ <xref linkend="llapi_file_get_stripe"/>
</para>
</listitem>
<listitem>
<para>
- <xref linkend="dbdoclet.50438215_86607"/>
+ <xref linkend="llapi_file_open"/>
</para>
</listitem>
<listitem>
<para>
- <xref linkend="dbdoclet.50438215_12433"/>
+ <xref linkend="llapi_quotactl"/>
</para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>
+<!--
+ vim:expandtab:shiftwidth=2:tabstop=8:
+ -->
git://git.whamcloud.com / doc / manual.git / blobdiff