<?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">
- <info>
- <title xml:id="settinglustreproperties.title">Setting Lustre Properties in a C Program (<literal>llapi</literal>)</title>
- </info>
+<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">
- <title>34.1 <literal>llapi_file_create</literal></title>
+ <section xml:id="llapi_file_create">
+ <title>
+ <literal>llapi_file_create</literal>
+ </title>
<para>Use <literal>llapi_file_create</literal> to set Lustre properties for a new file.</para>
<section remap="h5">
<title>Synopsis</title>
- <screen>#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+ <screen>#include <lustre/lustreapi.h>
int llapi_file_create(char *name, long stripe_size, int stripe_offset, int stripe_count, int stripe_pattern);
</screen>
</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*"/>
}</screen>
</section>
</section>
- <section xml:id="dbdoclet.50438215_50149">
- <title>34.2 llapi_file_get_stripe</title>
+ <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">
<title>Synopsis</title>
- <screen>#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <liblustre.h>
-#include <lustre/lustre_idl.h>
-#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+ <screen>
+#include <lustre/lustreapi.h>
int llapi_file_get_stripe(const char *<emphasis>path</emphasis>, void *<emphasis>lum</emphasis>);</screen>
</section>
<para> <literal>lmm_magic</literal></para>
</entry>
<entry>
- <para>Specifies the format of the returned striping information. <literal>LOV_MAGIC_V1</literal> isused for lov_user_md_v1. LOV_MAGIC_V3 is used for <literal>lov_user_md_v3</literal>.</para>
+ <para>Specifies the format of the returned striping information. <literal>LOV_MAGIC_V1</literal> is used for lov_user_md_v1. LOV_MAGIC_V3 is used for <literal>lov_user_md_v3</literal>.</para>
</entry>
</row>
<row>
<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>
</section>
<section remap="h5">
<title>Examples</title>
- <screen>#include <sys/vfs.h>
-#include <liblustre.h>
-#include <lnet/lnetctl.h>
-#include <obd.h>
-#include <lustre_lib.h>
-#include <lustre/liblustreapi.h>
-#include <obd_lov.h>
+ <programlisting>
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <lustre/lustreapi.h>
+
static inline int maxint(int a, int b)
{
-return a > b ? a : b;
+ return a > b ? a : b;
}
static void *alloc_lum()
{
-int v1, v3, join;
-v1 = sizeof(struct lov_user_md_v1) +
-LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
-v3 = sizeof(struct lov_user_md_v3) +
-LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
-return malloc(maxint(v1, v3));
+ int v1, v3, join;
+ v1 = sizeof(struct lov_user_md_v1) +
+ LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
+ v3 = sizeof(struct lov_user_md_v3) +
+ LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
+ return malloc(maxint(v1, v3));
}
int main(int argc, char** argv)
{
-struct lov_user_md *lum_file = NULL;
-int rc;
-int lum_size;
-if (argc != 2) {
-fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
-return 1;
-}
-lum_file = alloc_lum();
-if (lum_file == NULL) {
-rc = ENOMEM;
-goto cleanup;
-}
-rc = llapi_file_get_stripe(argv[1], lum_file);
-if (rc) {
-rc = errno;
-goto cleanup;
-}
-/* stripe_size stripe_count */
-printf("%d %d\n",
-lum_file->lmm_stripe_size,
-lum_file->lmm_stripe_count);
+ struct lov_user_md *lum_file = NULL;
+ int rc;
+ int lum_size;
+ if (argc != 2) {
+ fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
+ return 1;
+ }
+ lum_file = alloc_lum();
+ if (lum_file == NULL) {
+ rc = ENOMEM;
+ goto cleanup;
+ }
+ rc = llapi_file_get_stripe(argv[1], lum_file);
+ if (rc) {
+ rc = errno;
+ goto cleanup;
+ }
+ /* stripe_size stripe_count */
+ printf("%d %d\n",
+ lum_file->lmm_stripe_size,
+ lum_file->lmm_stripe_count);
cleanup:
-if (lum_file != NULL)
-free(lum_file);
-return rc;
-}</screen>
+ if (lum_file != NULL)
+ free(lum_file);
+ return rc;
+}
+</programlisting>
</section>
</section>
- <section xml:id="dbdoclet.50438215_86607">
- <title>34.3 <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>
+ <section xml:id="llapi_file_open">
+ <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 file system.</para>
<section remap="h5">
<title>Synopsis</title>
- <screen>#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <liblustre.h>
-#include <lustre/lustre_idl.h>
-#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+ <screen>#include <lustre/lustreapi.h>
int llapi_file_open(const char *<emphasis>name</emphasis>, int <emphasis>flags</emphasis>, int <emphasis>mode</emphasis>,
unsigned long long <emphasis>stripe_size</emphasis>, int <emphasis>stripe_offset</emphasis>,
int <emphasis>stripe_count</emphasis>, int <emphasis>stripe_pattern</emphasis>);
<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>EEXIST</literal></para>
</entry>
<entry>
- <para> triping information has already been set and cannot be altered; <literal>name</literal> already exists.</para>
+ <para>Striping information has already been set and cannot be altered; <literal>name</literal> already exists.</para>
</entry>
</row>
<row>
<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>
</section>
<section remap="h5">
<title>Example</title>
- <screen>#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <errno.h>
+ <programlisting>
#include <stdio.h>
-#include <liblustre.h>
-#include <lustre/lustre_idl.h>
-#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+#include <lustre/lustreapi.h>
+
int main(int argc, char *argv[])
{
- int rc;
- if (argc != 2)
- return -1;
- rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
- if (rc < 0) {
- fprintf(stderr, "file creation has failed, %s\n", strerror(-rc));
- return -1;
- }
- printf("%s with stripe size 1048576, striped across 2 OSTs,"
- " has been created!\n", argv[1]);
- return 0;
-}</screen>
+ int rc;
+ if (argc != 2)
+ return -1;
+ rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
+ if (rc < 0) {
+ fprintf(stderr, "file creation has failed, %s\n", strerror(-rc));
+ return -1;
+ }
+ printf("%s with stripe size 1048576, striped across 2 OSTs,"
+ " has been created!\n", argv[1]);
+ return 0;
+}
+</programlisting>
</section>
</section>
- <section xml:id="dbdoclet.50438215_12433">
- <title>34.4 <literal>llapi_quotactl</literal></title>
+ <section xml:id="llapi_quotactl">
+ <title>
+ <literal>llapi_quotactl</literal>
+ </title>
<para>Use <literal>llapi_quotact</literal>l to manipulate disk quotas on a Lustre file system.</para>
<section remap="h5">
<title>Synopsis</title>
- <screen>#include <liblustre.h>
-#include <lustre/lustre_idl.h>
-#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+ <screen>#include <lustre/lustreapi.h>
int llapi_quotactl(char" " *mnt," " struct if_quotactl" " *qctl)
struct if_quotactl {
<tbody>
<row>
<entry>
- <para> <literal>LUSTRE_Q_QUOTAON</literal></para>
- </entry>
- <entry>
- <para>Turns on quotas for a Lustre file system. <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.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para> <literal>LUSTRE_Q_QUOTAOFF</literal></para>
- </entry>
- <entry>
- <para>Turns off quotas for a Lustre file system. <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.</para>
- </entry>
- </row>
- <row>
- <entry>
<para> <literal>LUSTRE_Q_GETQUOTA</literal></para>
</entry>
<entry>
<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>
</tgroup>
</informaltable>
</section>
- <section remap="h5"><title>Return Values</title><para><literal>llapi_quotactl()</literal> returns:</para><para><literal>0</literal> On success</para><para><literal>
- -1
-</literal> On failure and sets error number (<literal>errno</literal>) to indicate the error</para></section>
+ <section remap="h5">
+ <title>Return Values</title>
+ <para><literal>llapi_quotactl()</literal> returns:</para>
+ <para><literal>0</literal> On success</para>
+ <para><literal> -1 </literal> On failure and sets error number (<literal>errno</literal>) to indicate the error</para>
+ </section>
<section remap="h5">
<title>Errors</title>
<para><literal>llapi_quotactl</literal> errors are described below.</para>
</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">
- <title>34.5 <literal>llapi_path2fid</literal></title>
+ <section xml:id="llapi_path2fid">
+ <title>
+ <literal>llapi_path2fid</literal>
+ </title>
<para>Use <literal>llapi_path2fid</literal> to get the FID from the pathname.</para>
<section remap="h5">
<title>Synopsis</title>
- <screen>#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+ <screen>#include <lustre/lustreapi.h>
int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid, unsigned long *ver)</screen>
</section>
<para>non-zero value On failure</para>
</section>
</section>
- <section xml:id="dbdoclet.50438215_marker-1297700">
- <title>34.6 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>You can set striping from inside programs like <literal>ioctl</literal>. To compile the sample program, you need to download libtest.c and liblustreapi.c files from the Lustre source tree.</para>
+ <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>
+ <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:
+ <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. 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>
+ </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>
+ 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
+ <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="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
+ 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>
- <screen>/* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
+ <programlisting>
+/* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
* vim:expandtab:shiftwidth=8:tabstop=8:
*
- * lustredemo - simple code examples of liblustreapi functions
+ * lustredemo - a simple example of lustreapi functions
*/
-
#include <stdio.h>
#include <fcntl.h>
-#include <sys/stat.h>
-#include <sys/types.h>
#include <dirent.h>
#include <errno.h>
-#include <string.h>
-#include <unistd.h>
#include <stdlib.h>
-#include <lustre/liblustreapi.h>
-#include <lustre/lustre_user.h>
+#include <lustre/lustreapi.h>
#define MAX_OSTS 1024
#define LOV_EA_SIZE(lum, num) (sizeof(*lum) + num * sizeof(*lum->lmm_objects))
#define LOV_EA_MAX(lum) LOV_EA_SIZE(lum, MAX_OSTS)
-
-
-
-
-/*
-This program provides crude examples of using the liblustre API functions
-*/
-
+/*
+ * This program provides crude examples of using the lustreapi API functions
+ */
/* Change these definitions to suit */
-
-
-
#define TESTDIR "/tmp" /* Results directory */
#define TESTFILE "lustre_dummy" /* Name for the file we create/destroy */
#define FILESIZE 262144 /* Size of the file in words */
#define DUMWORD "DEADBEEF" /* Dummy word used to fill files */
#define MY_STRIPE_WIDTH 2 /* Set this to the number of OST required */
#define MY_LUSTRE_DIR "/mnt/lustre/ftest"
-
-
+
int close_file(int fd)
-{
- if (close(fd) < 0) {
- fprintf(stderr, "File close failed: %d (%s)\n", errno, strerror(errno));
- return -1;
- }
- return 0;
+{
+ if (close(fd) < 0) {
+ fprintf(stderr, "File close failed: %d (%s)\n", errno, strerror(errno));
+ return -1;
+ }
+ return 0;
}
-
+
int write_file(int fd)
{
- char *stng = DUMWORD;
- int cnt = 0;
-
- for( cnt = 0; cnt < FILESIZE; cnt++) {
+ char *stng = DUMWORD;
+ int cnt = 0;
+
+ for( cnt = 0; cnt < FILESIZE; cnt++) {
write(fd, stng, sizeof(stng));
- }
- return 0;
+ }
+ return 0;
}
/* Open a file, set a specific stripe count, size and starting OST
- Adjust the parameters to suit */
-
+ * Adjust the parameters to suit */
int open_stripe_file()
{
- char *tfile = TESTFILE;
- int stripe_size = 65536; /* System default is 4M */
- int stripe_offset = -1; /* Start at default */
- int stripe_count = MY_STRIPE_WIDTH; /*Single stripe for this demo*/
- int stripe_pattern = 0; /* only RAID 0 at this time */
- int rc, fd;
- /*
- */
- rc = llapi_file_create(tfile,
-stripe_size,stripe_offset,stripe_count,stripe_pattern);
- /* result code is inverted, we may return -EINVAL or an ioctl error.
- We borrow an error message from sanity.c
- */
- if (rc) {
+ char *tfile = TESTFILE;
+ int stripe_size = 65536; /* System default is 4M */
+ int stripe_offset = -1; /* Start at default */
+ int stripe_count = MY_STRIPE_WIDTH; /*Single stripe for this demo*/
+ int stripe_pattern = 0; /* only RAID 0 at this time */
+ int rc, fd;
+
+ rc = llapi_file_create(tfile,
+ stripe_size,stripe_offset,stripe_count,stripe_pattern);
+ /* result code is inverted, we may return -EINVAL or an ioctl error.
+ * We borrow an error message from sanity.c
+ */
+ if (rc) {
fprintf(stderr,"llapi_file_create failed: %d (%s) \n", rc, strerror(-rc));
return -1;
}
/* llapi_file_create closes the file descriptor, we must re-open */
fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644);
if (fd < 0) {
- fprintf(stderr, "Can't open %s file: %d (%s)\n", tfile, errno, strerror(errno));
- return -1;
+ fprintf(stderr, "Can't open %s file: %d (%s)\n", tfile, errno, strerror(errno));
+ return -1;
}
return fd;
}
-
+
/* output a list of uuids for this file */
int get_my_uuids(int fd)
{
- struct obd_uuid uuids[1024], *uuidp; /* Output var */
- int obdcount = 1024;
- int rc,i;
-
- rc = llapi_lov_get_uuids(fd, uuids, &obdcount);
- if (rc != 0) {
- fprintf(stderr, "get uuids failed: %d (%s)\n",errno, strerror(errno));
+ struct obd_uuid uuids[1024], *uuidp; /* Output var */
+ int obdcount = 1024;
+ int rc,i;
+
+ rc = llapi_lov_get_uuids(fd, uuids, &obdcount);
+ if (rc != 0) {
+ fprintf(stderr, "get uuids failed: %d (%s)\n",errno, strerror(errno));
}
printf("This file system has %d obds\n", obdcount);
for (i = 0, uuidp = uuids; i < obdcount; i++, uuidp++) {
- printf("UUID %d is %s\n",i, uuidp->uuid);
+ printf("UUID %d is %s\n",i, uuidp->uuid);
}
return 0;
}
-
+
/* Print out some LOV attributes. List our objects */
int get_file_info(char *path)
{
-
- struct lov_user_md *lump;
- int rc;
- int i;
-
- lump = malloc(LOV_EA_MAX(lump));
- if (lump == NULL) {
- return -1;
+
+ struct lov_user_md *lump;
+ int rc;
+ int i;
+
+ lump = malloc(LOV_EA_MAX(lump));
+ if (lump == NULL) {
+ return -1;
}
-
+
rc = llapi_file_get_stripe(path, lump);
-
+
if (rc != 0) {
- fprintf(stderr, "get_stripe failed: %d (%s)\n",errno, strerror(errno));
- return -1;
+ fprintf(stderr, "get_stripe failed: %d (%s)\n",errno, strerror(errno));
+ return -1;
}
-
- printf("Lov magic %u\n", lump->lmm_magic);
- printf("Lov pattern %u\n", lump->lmm_pattern);
- printf("Lov object id %llu\n", lump->lmm_object_id);
- printf("Lov object group %llu\n", lump->lmm_object_gr);
- printf("Lov stripe size %u\n", lump->lmm_stripe_size);
- printf("Lov stripe count %hu\n", lump->lmm_stripe_count);
- printf("Lov stripe offset %u\n", lump->lmm_stripe_offset);
- for (i = 0; i < lump->lmm_stripe_count; i++) {
- printf("Object index %d Objid %llu\n", lump->lmm_objects[i].l_ost_idx, lump->lmm_objects[i].l_object_id);
+
+ printf("Lov magic %u\n", lump->lmm_magic);
+ printf("Lov pattern %u\n", lump->lmm_pattern);
+ printf("Lov object id %llu\n", lump->lmm_object_id);
+ printf("Lov stripe size %u\n", lump->lmm_stripe_size);
+ printf("Lov stripe count %hu\n", lump->lmm_stripe_count);
+ printf("Lov stripe offset %u\n", lump->lmm_stripe_offset);
+ for (i = 0; i < lump->lmm_stripe_count; i++) {
+ printf("Object index %d Objid %llu\n", lump->lmm_objects[i].l_ost_idx, lump->lmm_objects[i].l_object_id);
}
-
-
- free(lump);
- return rc;
-
+
+ free(lump);
+ return rc;
+
}
-/* Ping all OSTs that belong to this filesysem */
-
+
+/* Ping all OSTs that belong to this filesystem */
int ping_osts()
{
- DIR *dir;
- struct dirent *d;
- char osc_dir[100];
- int rc;
-
- sprintf(osc_dir, "/proc/fs/lustre/osc");
- dir = opendir(osc_dir);
- if (dir == NULL) {
- printf("Can't open dir\n");
- return -1;
- }
- while((d = readdir(dir)) != NULL) {
- if ( d->d_type == DT_DIR ) {
- if (! strncmp(d->d_name, "OSC", 3)) {
- printf("Pinging OSC %s ", d->d_name);
- rc = llapi_ping("osc", d->d_name);
- if (rc) {
- printf(" bad\n");
- } else {
- printf(" good\n");
- }
- }
- }
- }
- return 0;
-
+ DIR *dir;
+ struct dirent *d;
+ char osc_dir[100];
+ int rc;
+
+ sprintf(osc_dir, "/proc/fs/lustre/osc");
+ dir = opendir(osc_dir);
+ if (dir == NULL) {
+ printf("Can't open dir\n");
+ return -1;
+ }
+ while((d = readdir(dir)) != NULL) {
+ if ( d->d_type == DT_DIR ) {
+ if (! strncmp(d->d_name, "OSC", 3)) {
+ printf("Pinging OSC %s ", d->d_name);
+ rc = llapi_ping("osc", d->d_name);
+ if (rc) {
+ printf(" bad\n");
+ } else {
+ printf(" good\n");
+ }
+ }
+ }
+ }
+ return 0;
+
}
-
+
int main()
{
- int file;
- int rc;
- char filename[100];
- char sys_cmd[100];
-
- sprintf(filename, "%s/%s",MY_LUSTRE_DIR, TESTFILE);
-
- printf("Open a file with striping\n");
- file = open_stripe_file();
- if ( file < 0 ) {
- printf("Exiting\n");
- exit(1);
-
-
-
-
- }
- printf("Getting uuid list\n");
- rc = get_my_uuids(file);
- rintf("Write to the file\n");
- rc = write_file(file);
- rc = close_file(file);
- printf("Listing LOV data\n");
- rc = get_file_info(filename);
- printf("Ping our OSTs\n");
- rc = ping_osts();
-
- /* the results should match lfs getstripe */
- printf("Confirming our results with lfs getsrtipe\n");
- sprintf(sys_cmd, "/usr/bin/lfs getstripe %s/%s", MY_LUSTRE_DIR, TESTFILE);
- system(sys_cmd);
-
- printf("All done\n");
- exit(rc);
-}
-</screen>
+ int file;
+ int rc;
+ char filename[100];
+ char sys_cmd[100];
+
+ sprintf(filename, "%s/%s",MY_LUSTRE_DIR, TESTFILE);
+
+ printf("Open a file with striping\n");
+ file = open_stripe_file();
+ if ( file < 0 ) {
+ printf("Exiting\n");
+ exit(1);
+ }
+ printf("Getting uuid list\n");
+ rc = get_my_uuids(file);
+ printf("Write to the file\n");
+ rc = write_file(file);
+ rc = close_file(file);
+ printf("Listing LOV data\n");
+ rc = get_file_info(filename);
+ printf("Ping our OSTs\n");
+ rc = ping_osts();
+
+ /* the results should match lfs getstripe */
+ printf("Confirming our results with lfs getstripe\n");
+ sprintf(sys_cmd, "/usr/bin/lfs getstripe %s/%s", MY_LUSTRE_DIR, TESTFILE);
+ system(sys_cmd);
+
+ printf("All done\n");
+ exit(rc);
+}
+</programlisting>
<para><emphasis role="bold">Makefile for sample application:</emphasis></para>
<screen>
gcc -g -O2 -Wall -o lustredemo libtest.c -llustreapi
</screen>
<section remap="h5">
<title>See Also</title>
- <itemizedlist>
- <listitem>
- <para>
- <xref linkend="dbdoclet.50438215_30970"/>
+ <itemizedlist>
+ <listitem>
+ <xref linkend="llapi_file_create"/>
</para>
- </listitem>
- <listitem>
- <para>
- <xref linkend="dbdoclet.50438215_50149"/>
+ </listitem>
+ <listitem>
+ <xref linkend="llapi_file_get_stripe"/>
</para>
- </listitem>
- <listitem>
- <para>
- <xref linkend="dbdoclet.50438215_86607"/>
+ </listitem>
+ <listitem>
+ <xref linkend="llapi_file_open"/>
</para>
- </listitem>
- <listitem>
- <para>
- <xref linkend="dbdoclet.50438215_12433"/>
+ </listitem>
+ <listitem>
+ <xref linkend="llapi_quotactl"/>
</para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
</section>
</section>
</chapter>
+<!--
+ vim:expandtab:shiftwidth=2:tabstop=8:
+ -->
git://git.whamcloud.com / doc / manual.git / blobdiff