1 <?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">
2 <title xml:id="settinglustreproperties.title">Setting Lustre Properties in a C Program (<literal>llapi</literal>)</title>
3 <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>
6 <para><xref linkend="dbdoclet.50438215_30970"/></para>
9 <para><xref linkend="dbdoclet.50438215_50149"/></para>
12 <para><xref linkend="dbdoclet.50438215_86607"/></para>
15 <para><xref linkend="dbdoclet.50438215_12433"/></para>
18 <para><xref linkend="dbdoclet.50438215_15718"/></para>
22 <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
24 <section xml:id="dbdoclet.50438215_30970">
26 <literal>llapi_file_create</literal>
28 <para>Use <literal>llapi_file_create</literal> to set Lustre properties for a new file.</para>
30 <title>Synopsis</title>
31 <screen>#include <lustre/lustreapi.h>
33 int llapi_file_create(char *name, long stripe_size, int stripe_offset, int stripe_count, int stripe_pattern);
37 <title>Description</title>
38 <para>The <literal>llapi_file_create()</literal> function sets a file descriptor's Lustre
39 file system striping information. The file descriptor is then accessed with
40 <literal>open()</literal>.</para>
41 <informaltable frame="all">
43 <colspec colname="c1" colwidth="50*"/>
44 <colspec colname="c2" colwidth="50*"/>
48 <para><emphasis role="bold">Option</emphasis></para>
51 <para><emphasis role="bold">Description</emphasis></para>
58 <para> <literal>llapi_file_create()</literal></para>
61 <para>If the file already exists, this parameter returns to '<literal>EEXIST</literal>'. If the stripe parameters are invalid, this parameter returns to '<literal>EINVAL</literal>'.</para>
66 <para> <literal>stripe_size</literal></para>
69 <para>This value must be an even multiple of system page size, as shown by <literal>getpagesize()</literal>. The default Lustre stripe size is 4MB.</para>
74 <para> <literal>stripe_offset</literal></para>
77 <para>Indicates the starting OST for this file.</para>
82 <para> <literal>stripe_count</literal></para>
85 <para>Indicates the number of OSTs that this file will be striped across.</para>
90 <para> <literal>stripe_pattern</literal></para>
93 <para>Indicates the RAID pattern.</para>
100 <para>Currently, only RAID 0 is supported. To use the system defaults, set these values: <literal>stripe_size</literal> = 0, <literal>stripe_offset</literal> = -1, <literal>stripe_count</literal> = 0, <literal>stripe_pattern</literal> = 0</para>
104 <title>Examples</title>
105 <para>System default size is 4 MB.</para>
106 <screen>char *tfile = TESTFILE;
107 int stripe_size = 65536</screen>
108 <para>To start at default, run:</para>
109 <screen>int stripe_offset = -1</screen>
110 <para>To start at the default, run:</para>
111 <screen>int stripe_count = 1</screen>
112 <para>To set a single stripe for this example, run:</para>
113 <screen>int stripe_pattern = 0</screen>
114 <para>Currently, only RAID 0 is supported.</para>
115 <screen>int stripe_pattern = 0;
117 rc = llapi_file_create(tfile, stripe_size,stripe_offset, stripe_count,stripe_pattern);</screen>
118 <para>Result code is inverted, you may return with '<literal>EINVAL</literal>' or an ioctl error.</para>
120 fprintf(stderr,"llapi_file_create failed: %d (%s) 0, rc, strerror(-rc));return -1; }</screen>
121 <para><literal>llapi_file_create</literal> closes the file descriptor. You must re-open the descriptor. To do this, run:</para>
122 <screen>fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644); if (fd < 0) \ {
123 fprintf(stderr, "Can't open %s file: %s0, tfile,
130 <section xml:id="dbdoclet.50438215_50149">
131 <title>llapi_file_get_stripe</title>
132 <para>Use <literal>llapi_file_get_stripe</literal> to get striping information for a file or directory on a Lustre file system.</para>
134 <title>Synopsis</title>
136 #include <lustre/lustreapi.h>
138 int llapi_file_get_stripe(const char *<emphasis>path</emphasis>, void *<emphasis>lum</emphasis>);</screen>
141 <title>Description</title>
142 <para>The <literal>llapi_file_get_stripe()</literal> function returns striping information for a file or directory <emphasis>path</emphasis> in <emphasis>lum</emphasis> (which should point to a large enough memory region) in one of the following formats:</para>
143 <screen>struct lov_user_md_v1 {
147 __u64 lmm_object_seq;
148 __u32 lmm_stripe_size;
149 __u16 lmm_stripe_count;
150 __u16 lmm_stripe_offset;
151 struct lov_user_ost_data_v1 lmm_objects[0];
152 } __attribute__((packed));
153 struct lov_user_md_v3 {
157 __u64 lmm_object_seq;
158 __u32 lmm_stripe_size;
159 __u16 lmm_stripe_count;
160 __u16 lmm_stripe_offset;
161 char lmm_pool_name[LOV_MAXPOOLNAME];
162 struct lov_user_ost_data_v1 lmm_objects[0];
163 } __attribute__((packed));</screen>
164 <informaltable frame="all">
166 <colspec colname="c1" colwidth="50*"/>
167 <colspec colname="c2" colwidth="50*"/>
171 <para><emphasis role="bold">Option</emphasis></para>
174 <para><emphasis role="bold">Description</emphasis></para>
181 <para> <literal>lmm_magic</literal></para>
184 <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>
189 <para> <literal>lmm_pattern</literal></para>
192 <para>Holds the striping pattern. Only <literal>LOV_PATTERN_RAID0</literal> is
193 possible in this Lustre software release.</para>
198 <para> <literal>lmm_object_id</literal></para>
201 <para>Holds the MDS object ID.</para>
206 <para> <literal>lmm_object_gr</literal></para>
209 <para>Holds the MDS object group.</para>
214 <para> <literal>lmm_stripe_size</literal></para>
217 <para>Holds the stripe size in bytes.</para>
222 <para> <literal>lmm_stripe_count</literal></para>
225 <para>Holds the number of OSTs over which the file is striped.</para>
230 <para> <literal>lmm_stripe_offset</literal></para>
233 <para>Holds the OST index from which the file starts.</para>
238 <para> <literal>lmm_pool_name</literal></para>
241 <para>Holds the OST pool name to which the file belongs.</para>
246 <para> <literal>lmm_objects</literal></para>
249 <para>An array of <literal>lmm_stripe_count</literal> members containing per OST file information in</para>
250 <para>the following format:</para>
251 <screen>struct lov_user_ost_data_v1 {
256 } __attribute__((packed));</screen>
261 <para> <literal>l_object_id</literal></para>
264 <para>Holds the OST's object ID.</para>
269 <para> <literal>l_object_seq</literal></para>
272 <para>Holds the OST's object group.</para>
277 <para> <literal>l_ost_gen</literal></para>
280 <para>Holds the OST's index generation.</para>
285 <para> <literal>l_ost_idx</literal></para>
288 <para>Holds the OST's index in LOV.</para>
296 <title>Return Values</title>
297 <para><literal>llapi_file_get_stripe()</literal> returns:</para>
298 <para><literal>0</literal> On success</para>
299 <para><literal>!= 0</literal> On failure, <literal>errno</literal> is set appropriately</para>
302 <title>Errors</title>
303 <informaltable frame="all">
305 <colspec colname="c1" colwidth="50*"/>
306 <colspec colname="c2" colwidth="50*"/>
310 <para><emphasis role="bold">Errors</emphasis></para>
313 <para><emphasis role="bold">Description</emphasis></para>
320 <para> <literal>ENOMEM</literal></para>
323 <para>Failed to allocate memory</para>
328 <para> <literal>ENAMETOOLONG</literal></para>
331 <para>Path was too long</para>
336 <para> <literal>ENOENT</literal></para>
339 <para>Path does not point to a file or directory</para>
344 <para> <literal>ENOTTY</literal></para>
347 <para>Path does not point to a Lustre file system</para>
352 <para> <literal>EFAULT</literal></para>
355 <para>Memory region pointed by lum is not properly mapped</para>
363 <title>Examples</title>
365 #include <stdio.h>
366 #include <stdlib.h>
367 #include <errno.h>
368 #include <lustre/lustreapi.h>
370 static inline int maxint(int a, int b)
372 return a > b ? a : b;
374 static void *alloc_lum()
377 v1 = sizeof(struct lov_user_md_v1) +
378 LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
379 v3 = sizeof(struct lov_user_md_v3) +
380 LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
381 return malloc(maxint(v1, v3));
383 int main(int argc, char** argv)
385 struct lov_user_md *lum_file = NULL;
389 fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
392 lum_file = alloc_lum();
393 if (lum_file == NULL) {
397 rc = llapi_file_get_stripe(argv[1], lum_file);
402 /* stripe_size stripe_count */
403 printf("%d %d\n",
404 lum_file->lmm_stripe_size,
405 lum_file->lmm_stripe_count);
407 if (lum_file != NULL)
414 <section xml:id="dbdoclet.50438215_86607">
416 <literal>llapi_file_open</literal>
418 <para>The <literal>llapi_file_open</literal> command opens (or creates) a file or device on a
419 Lustre file system.</para>
421 <title>Synopsis</title>
422 <screen>#include <lustre/lustreapi.h>
423 int llapi_file_open(const char *<emphasis>name</emphasis>, int <emphasis>flags</emphasis>, int <emphasis>mode</emphasis>,
424 unsigned long long <emphasis>stripe_size</emphasis>, int <emphasis>stripe_offset</emphasis>,
425 int <emphasis>stripe_count</emphasis>, int <emphasis>stripe_pattern</emphasis>);
426 int llapi_file_create(const char *<emphasis>name</emphasis>, unsigned long long <emphasis>stripe_size</emphasis>,
427 int <emphasis>stripe_offset</emphasis>, int <emphasis>stripe_count</emphasis>,
428 int <emphasis>stripe_pattern</emphasis>);
432 <title>Description</title>
433 <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>
434 <para><literal>llapi_file_open()</literal> opens a file with a given name on a Lustre file
436 <informaltable frame="all">
438 <colspec colname="c1" colwidth="50*"/>
439 <colspec colname="c2" colwidth="50*"/>
443 <para><emphasis role="bold">Option</emphasis></para>
446 <para><emphasis role="bold">Description</emphasis></para>
453 <para> <literal>flags</literal></para>
456 <para>Can be a combination of <literal>O_RDONLY</literal>, <literal>O_WRONLY</literal>, <literal>O_RDWR</literal>, <literal>O_CREAT</literal>, <literal>O_EXCL</literal>, <literal>O_NOCTTY</literal>, <literal>O_TRUNC</literal>, <literal>O_APPEND</literal>, <literal>O_NONBLOCK</literal>, <literal>O_SYNC</literal>, <literal>FASYNC</literal>, <literal>O_DIRECT</literal>, <literal>O_LARGEFILE</literal>, <literal>O_DIRECTORY</literal>, <literal>O_NOFOLLOW</literal>, <literal>O_NOATIME</literal>.</para>
461 <para> <literal>mode</literal></para>
464 <para>Specifies the permission bits to be used for a new file when <literal>O_CREAT</literal> is used.</para>
469 <para> <literal>stripe_size</literal></para>
472 <para>Specifies stripe size (in bytes). Should be multiple of 64 KB, not exceeding 4 GB.</para>
477 <para> <literal>stripe_offset</literal></para>
480 <para>Specifies an OST index from which the file should start. The default value is -1.</para>
485 <para> <literal>stripe_count</literal></para>
488 <para>Specifies the number of OSTs to stripe the file across. The default value is -1.</para>
493 <para> <literal>stripe_pattern</literal></para>
496 <para>Specifies the striping pattern. In this release of the Lustre software, only
497 <literal>LOV_PATTERN_RAID0</literal> is available. The default value is
506 <title>Return Values</title>
507 <para><literal>llapi_file_open()</literal> and <literal>llapi_file_create()</literal> return:</para>
508 <para><literal>>=0</literal> On success, for <literal>llapi_file_open</literal> the return value is a file descriptor</para>
509 <para><literal><0</literal> On failure, the absolute value is an error code</para>
512 <title>Errors</title>
513 <informaltable frame="all">
515 <colspec colname="c1" colwidth="50*"/>
516 <colspec colname="c2" colwidth="50*"/>
520 <para><emphasis role="bold">Errors</emphasis></para>
523 <para><emphasis role="bold">Description</emphasis></para>
530 <para> <literal>EINVAL</literal></para>
533 <para><literal>stripe_size</literal> or <literal>stripe_offset</literal> or <literal>stripe_count</literal> or <literal>stripe_pattern</literal> is invalid.</para>
538 <para> <literal>EEXIST</literal></para>
541 <para>Striping information has already been set and cannot be altered; <literal>name</literal> already exists.</para>
546 <para> <literal>EALREADY</literal></para>
549 <para>Striping information has already been set and cannot be altered</para>
554 <para> <literal>ENOTTY</literal></para>
558 <literal>name</literal> may not point to a Lustre file system.</para>
566 <title>Example</title>
568 #include <stdio.h>
569 #include <lustre/lustreapi.h>
571 int main(int argc, char *argv[])
576 rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
578 fprintf(stderr, "file creation has failed, %s\n", strerror(-rc));
581 printf("%s with stripe size 1048576, striped across 2 OSTs,"
582 " has been created!\n", argv[1]);
588 <section xml:id="dbdoclet.50438215_12433">
590 <literal>llapi_quotactl</literal>
592 <para>Use <literal>llapi_quotact</literal>l to manipulate disk quotas on a Lustre file system.</para>
594 <title>Synopsis</title>
595 <screen>#include <lustre/lustreapi.h>
596 int llapi_quotactl(char" " *mnt," " struct if_quotactl" " *qctl)
603 struct obd_dqinfo qc_dqinfo;
604 struct obd_dqblk qc_dqblk;
606 struct obd_uuid obd_uuid;
609 __u64 dqb_bhardlimit;
610 __u64 dqb_bsoftlimit;
612 __u64 dqb_ihardlimit;
613 __u64 dqb_isoftlimit;
631 <title>Description</title>
632 <para>The <literal>llapi_quotactl()</literal> command manipulates disk quotas on a Lustre file system mount. qc_cmd indicates a command to be applied to UID <literal>qc_id</literal> or GID <literal>qc_id</literal>.</para>
633 <informaltable frame="all">
635 <colspec colname="c1" colwidth="50*"/>
636 <colspec colname="c2" colwidth="50*"/>
640 <para><emphasis role="bold">Option</emphasis></para>
643 <para><emphasis role="bold">Description</emphasis></para>
650 <para> <literal>LUSTRE_Q_QUOTAON</literal></para>
653 <para>Turns on quotas for a Lustre file system. Deprecated as of 2.4.0.
654 <emphasis>qc_type</emphasis> is <literal>USRQUOTA</literal>,
655 <literal>GRPQUOTA</literal> or <literal>UGQUOTA</literal> (both user and group
656 quota). The quota files must exist. They are normally created with the
657 <literal>llapi_quotacheck</literal> call. This call is restricted to the super
658 user privilege. As of 2.4.0, quota is now enabled on a per file system basis via
659 <literal>lctl conf_param</literal> (see <xref linkend="enabling_disk_quotas"/>)
660 on the MGS node and quotacheck isn't needed any more.</para>
665 <para> <literal>LUSTRE_Q_QUOTAOFF</literal></para>
668 <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>
673 <para> <literal>LUSTRE_Q_GETQUOTA</literal></para>
676 <para>Gets disk quota limits and current usage for user or group <emphasis>qc_id</emphasis>. <emphasis>qc_type</emphasis> is <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. <emphasis>uuid</emphasis> may be filled with <literal>OBD UUID</literal> string to query quota information from a specific node. <emphasis>dqb_valid</emphasis> may be set nonzero to query information only from MDS. If <emphasis>uuid</emphasis> is an empty string and <emphasis>dqb_valid</emphasis> is zero then cluster-wide limits and usage are returned. On return, <emphasis>obd_dqblk</emphasis> contains the requested information (block limits unit is kilobyte). Quotas must be turned on before using this command.</para>
681 <para> <literal>LUSTRE_Q_SETQUOTA</literal></para>
684 <para>Sets disk quota limits for user or group <emphasis>qc_id</emphasis>. <emphasis>qc_type</emphasis> is <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. <emphasis>dqb_valid</emphasis> must be set to <literal>QIF_ILIMITS</literal>, <literal>QIF_BLIMITS</literal> or <literal>QIF_LIMITS</literal> (both inode limits and block limits) dependent on updating limits. <emphasis>obd_dqblk</emphasis> must be filled with limits values (as set in <emphasis>dqb_valid</emphasis>, block limits unit is kilobyte). Quotas must be turned on before using this command.</para>
689 <para> <literal>LUSTRE_Q_GETINFO</literal></para>
692 <para>Gets information about quotas. <emphasis>qc_type</emphasis> is either
693 <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>. On return,
694 <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds),
695 <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds),
696 <emphasis>dqi_flags</emphasis> is not used by the current release of the Lustre
702 <para> <literal>LUSTRE_Q_SETINFO</literal></para>
705 <para>Sets quota information (like grace times). <emphasis>qc_type</emphasis> is
706 either <literal>USRQUOTA</literal> or <literal>GRPQUOTA</literal>.
707 <emphasis>dqi_igrace</emphasis> is inode grace time (in seconds),
708 <emphasis>dqi_bgrace</emphasis> is block grace time (in seconds),
709 <emphasis>dqi_flags</emphasis> is not used by the current release of the Lustre
710 software and must be zeroed.</para>
718 <title>Return Values</title>
719 <para><literal>llapi_quotactl()</literal> returns:</para>
720 <para><literal>0</literal> On success</para>
721 <para><literal> -1 </literal> On failure and sets error number (<literal>errno</literal>) to indicate the error</para>
724 <title>Errors</title>
725 <para><literal>llapi_quotactl</literal> errors are described below.</para>
726 <informaltable frame="all">
728 <colspec colname="c1" colwidth="50*"/>
729 <colspec colname="c2" colwidth="50*"/>
733 <para><emphasis role="bold">Errors</emphasis></para>
736 <para><emphasis role="bold">Description</emphasis></para>
743 <para> <literal>EFAULT</literal></para>
746 <para><emphasis>qctl</emphasis> is invalid.</para>
751 <para> <literal>ENOSYS</literal></para>
754 <para>Kernel or Lustre modules have not been compiled with the <literal>QUOTA</literal> option.</para>
759 <para> <literal>ENOMEM</literal></para>
762 <para>Insufficient memory to complete operation.</para>
767 <para> <literal>ENOTTY</literal></para>
770 <para> <emphasis>qc_cmd</emphasis> is invalid.</para>
775 <para> <literal>EBUSY</literal></para>
778 <para>Cannot process during quotacheck.</para>
783 <para> <literal>ENOENT</literal></para>
786 <para> <emphasis>uuid</emphasis> does not correspond to OBD or <emphasis>mnt</emphasis> does not exist.</para>
791 <para> <literal>EPERM</literal></para>
794 <para>The call is privileged and the caller is not the super user.</para>
799 <para> <literal>ESRCH</literal></para>
802 <para>No disk quota is found for the indicated user. Quotas have not been turned on for this file system.</para>
810 <section xml:id="dbdoclet.50438215_15718">
812 <literal>llapi_path2fid</literal>
814 <para>Use <literal>llapi_path2fid</literal> to get the FID from the pathname.</para>
816 <title>Synopsis</title>
817 <screen>#include <lustre/lustreapi.h>
819 int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid, unsigned long *ver)</screen>
822 <title>Description</title>
823 <para>The <literal>llapi_path2fid</literal> function returns the FID (sequence : object ID : version) for the pathname.</para>
826 <title>Return Values</title>
827 <para><literal>llapi_path2fid</literal> returns:</para>
828 <para><literal>0</literal> On success</para>
829 <para>non-zero value On failure</para>
832 <section condition="l29">
834 <literal>llapi_ladvise</literal>
836 <para>Use <literal>llapi_ladvise</literal> to give IO advice/hints on a
837 Lustre file to the server.</para>
839 <title>Synopsis</title>
841 #include <lustre/lustreapi.h>
842 int llapi_ladvise(int fd, unsigned long long flags,
843 int num_advise, struct llapi_lu_ladvise *ladvise);
845 struct llapi_lu_ladvise {
846 __u16 lla_advice; /* advice type */
847 __u16 lla_value1; /* values for different advice types */
849 __u64 lla_start; /* first byte of extent for advice */
850 __u64 lla_end; /* last byte of extent for advice */
857 <title>Description</title>
858 <para>The <literal>llapi_ladvise</literal> function passes an array of
859 <emphasis>num_advise</emphasis> I/O hints (up to a maximum of
860 <emphasis>LAH_COUNT_MAX</emphasis> items) in ladvise for the file
861 descriptor <emphasis>fd</emphasis> from an application to one or more
862 Lustre servers. Optionally, <emphasis>flags</emphasis> can modify how
863 the advice will be processed via bitwise-or'd values:</para>
864 <itemizedlist><listitem>
865 <para><literal>LF_ASYNC</literal>: Clients return to userspace
866 immediately after submitting ladvise RPCs, leaving server threads to
867 handle the advices asynchronously.</para>
868 </listitem></itemizedlist>
869 <para>Each of the <emphasis>ladvise</emphasis> elements is an
870 <emphasis>llapi_lu_ladvise</emphasis> structure, which contains the
872 <informaltable frame="all">
874 <colspec colname="c1" colwidth="50*"/>
875 <colspec colname="c2" colwidth="50*"/>
879 <para><emphasis role="bold">Field</emphasis></para>
882 <para><emphasis role="bold">Description</emphasis></para>
889 <para> <literal>lla_ladvice</literal></para>
892 <para>Specifies the advice for the given file range, currently
894 <para><literal>LU_LADVISE_WILLREAD</literal>: Prefetch data
895 into server cache using optimum I/O size for the server.</para>
896 <para><literal>LU_LADVISE_DONTNEED</literal>: Clean cached data
897 for the specified file range(s) on the server.</para>
902 <para> <literal>lla_start</literal></para>
905 <para>The offset in bytes for the start of this advice.</para>
910 <para> <literal>lla_end</literal></para>
913 <para>The offset in bytes (non-inclusive) for the end of this
919 <para> <literal>lla_value1</literal></para>
920 <para> <literal>lla_value2</literal></para>
921 <para> <literal>lla_value3</literal></para>
922 <para> <literal>lla_value4</literal></para>
925 <para>Additional arguments for future advice types and
926 should be set to zero if not explicitly required for a given
927 advice type. Advice-specific names for these fields
933 <para> <literal>lla_lockahead_mode</literal></para>
936 <para>When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field
937 is used to communicate the requested lock mode, and can be
938 referred to as lla_lockahead_mode.</para>
943 <para> <literal>lla_peradvice_flags</literal></para>
946 <para>When using advices which support them, the 'lla_value2'
947 field is used to communicate per-advice flags and can be
948 referred to as 'lla_peradvice_flags'.</para>
953 <para> <literal>lla_lockahead_result</literal></para>
956 <para>When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field
957 is used to communicate the result of the request, and can be
958 referred to as lla_lockahead_result.</para>
965 <para><literal>llapi_ladvise()</literal> forwards the advice to Lustre
966 servers without guaranteeing how and when servers will react to the
967 advice. Actions may or may not be triggered when the advices are
968 received, depending on the type of the advice as well as the real-time
969 decision of the affected server-side components.
971 <para> A typical usage of <literal>llapi_ladvise()</literal> is to
972 enable applications and users (via <literal>lfs ladvise</literal>)
973 with external knowledge about application I/O patterns to intervene in
974 server-side I/O handling. For example, if a group of different clients
975 are doing small random reads of a file, prefetching pages into OSS
976 cache with big linear reads before the random IO is an overall net
977 benefit. Fetching that data into each client cache with
978 <emphasis>fadvise()</emphasis> may not be beneficial, due to much more
979 data being sent to the clients.
982 LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible
983 and encouraged to use it directly in your application to avoid lock
984 contention (primarily for writing to a single file from multiple
985 clients), it will also be available in the MPI-I/O / MPICH library
986 from ANL for use with the i/o aggregation mode of that library. This
987 is intended (eventually) to be the primary way this feature is used.
990 At the time of writing, this support is proposed as a patch but is
991 not yet merged in to the public ANL code base. Users are encouraged
992 to check their MPICH documentation and/or check with their library
993 provider about support.
995 <para>While conceptually similar to the
996 <emphasis>posix_fadvise</emphasis> and Linux
997 <emphasis>fadvise</emphasis> system calls, the main difference of
998 <literal>llapi_ladvise()</literal> is that
999 <emphasis>fadvise() / posix_fadvise()</emphasis> are client side
1000 mechanisms that do not pass advice to the filesystem, while
1001 <literal>llapi_ladvise()</literal> sends advice or hints to one or
1002 more Lustre servers on which the file is stored. In some cases it may
1003 be desirable to use both interfaces.
1006 <section remap="h5">
1007 <title>Return Values</title>
1008 <para><literal>llapi_ladvise</literal> returns:</para>
1009 <para><literal>0</literal> On success</para>
1010 <para><literal>-1</literal> if an error occurred (in which case, errno
1011 is set appropriately).</para>
1013 <section remap="h5">
1014 <title>Errors</title>
1016 <informaltable frame="all">
1018 <colspec colname="c1" colwidth="50*"/>
1019 <colspec colname="c2" colwidth="50*"/>
1023 <para><emphasis role="bold">Error</emphasis></para>
1026 <para><emphasis role="bold">Description</emphasis></para>
1033 <para> <literal>ENOMEM</literal></para>
1036 <para>Insufficient memory to complete operation.</para>
1041 <para> <literal>EINVAL</literal></para>
1044 <para>One or more invalid arguments are given.</para>
1049 <para> <literal>EFAULT</literal></para>
1052 <para>Memory region pointed by
1053 <literal>ladvise</literal> is not properly mapped.
1059 <para> <literal>ENOTSUPP</literal></para>
1062 <para>Advice type is not supported.</para>
1071 <section xml:id="dbdoclet.50438215_marker-1297700">
1072 <title>Example Using the <literal>llapi</literal> Library</title>
1073 <para>Use <literal>llapi_file_create</literal> to set Lustre software properties for a new file.
1074 For a synopsis and description of <literal>llapi_file_create</literal> and examples of how to
1075 use it, see <xref linkend="configurationfilesmoduleparameters"/>.</para>
1076 <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>
1077 <para><emphasis role="bold">A simple C program to demonstrate striping API - libtest.c</emphasis></para>
1079 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
1080 * vim:expandtab:shiftwidth=8:tabstop=8:
1082 * lustredemo - a simple example of lustreapi functions
1084 #include <stdio.h>
1085 #include <fcntl.h>
1086 #include <dirent.h>
1087 #include <errno.h>
1088 #include <stdlib.h>
1089 #include <lustre/lustreapi.h>
1090 #define MAX_OSTS 1024
1091 #define LOV_EA_SIZE(lum, num) (sizeof(*lum) + num * sizeof(*lum->lmm_objects))
1092 #define LOV_EA_MAX(lum) LOV_EA_SIZE(lum, MAX_OSTS)
1095 * This program provides crude examples of using the lustreapi API functions
1097 /* Change these definitions to suit */
1099 #define TESTDIR "/tmp" /* Results directory */
1100 #define TESTFILE "lustre_dummy" /* Name for the file we create/destroy */
1101 #define FILESIZE 262144 /* Size of the file in words */
1102 #define DUMWORD "DEADBEEF" /* Dummy word used to fill files */
1103 #define MY_STRIPE_WIDTH 2 /* Set this to the number of OST required */
1104 #define MY_LUSTRE_DIR "/mnt/lustre/ftest"
1106 int close_file(int fd)
1108 if (close(fd) < 0) {
1109 fprintf(stderr, "File close failed: %d (%s)\n", errno, strerror(errno));
1115 int write_file(int fd)
1117 char *stng = DUMWORD;
1120 for( cnt = 0; cnt < FILESIZE; cnt++) {
1121 write(fd, stng, sizeof(stng));
1125 /* Open a file, set a specific stripe count, size and starting OST
1126 * Adjust the parameters to suit */
1127 int open_stripe_file()
1129 char *tfile = TESTFILE;
1130 int stripe_size = 65536; /* System default is 4M */
1131 int stripe_offset = -1; /* Start at default */
1132 int stripe_count = MY_STRIPE_WIDTH; /*Single stripe for this demo*/
1133 int stripe_pattern = 0; /* only RAID 0 at this time */
1136 rc = llapi_file_create(tfile,
1137 stripe_size,stripe_offset,stripe_count,stripe_pattern);
1138 /* result code is inverted, we may return -EINVAL or an ioctl error.
1139 * We borrow an error message from sanity.c
1142 fprintf(stderr,"llapi_file_create failed: %d (%s) \n", rc, strerror(-rc));
1145 /* llapi_file_create closes the file descriptor, we must re-open */
1146 fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644);
1148 fprintf(stderr, "Can't open %s file: %d (%s)\n", tfile, errno, strerror(errno));
1154 /* output a list of uuids for this file */
1155 int get_my_uuids(int fd)
1157 struct obd_uuid uuids[1024], *uuidp; /* Output var */
1158 int obdcount = 1024;
1161 rc = llapi_lov_get_uuids(fd, uuids, &obdcount);
1163 fprintf(stderr, "get uuids failed: %d (%s)\n",errno, strerror(errno));
1165 printf("This file system has %d obds\n", obdcount);
1166 for (i = 0, uuidp = uuids; i < obdcount; i++, uuidp++) {
1167 printf("UUID %d is %s\n",i, uuidp->uuid);
1172 /* Print out some LOV attributes. List our objects */
1173 int get_file_info(char *path)
1176 struct lov_user_md *lump;
1180 lump = malloc(LOV_EA_MAX(lump));
1185 rc = llapi_file_get_stripe(path, lump);
1188 fprintf(stderr, "get_stripe failed: %d (%s)\n",errno, strerror(errno));
1192 printf("Lov magic %u\n", lump->lmm_magic);
1193 printf("Lov pattern %u\n", lump->lmm_pattern);
1194 printf("Lov object id %llu\n", lump->lmm_object_id);
1195 printf("Lov stripe size %u\n", lump->lmm_stripe_size);
1196 printf("Lov stripe count %hu\n", lump->lmm_stripe_count);
1197 printf("Lov stripe offset %u\n", lump->lmm_stripe_offset);
1198 for (i = 0; i < lump->lmm_stripe_count; i++) {
1199 printf("Object index %d Objid %llu\n", lump->lmm_objects[i].l_ost_idx, lump->lmm_objects[i].l_object_id);
1207 /* Ping all OSTs that belong to this filesystem */
1215 sprintf(osc_dir, "/proc/fs/lustre/osc");
1216 dir = opendir(osc_dir);
1218 printf("Can't open dir\n");
1221 while((d = readdir(dir)) != NULL) {
1222 if ( d->d_type == DT_DIR ) {
1223 if (! strncmp(d->d_name, "OSC", 3)) {
1224 printf("Pinging OSC %s ", d->d_name);
1225 rc = llapi_ping("osc", d->d_name);
1227 printf(" bad\n");
1229 printf(" good\n");
1245 sprintf(filename, "%s/%s",MY_LUSTRE_DIR, TESTFILE);
1247 printf("Open a file with striping\n");
1248 file = open_stripe_file();
1249 if ( file < 0 ) {
1250 printf("Exiting\n");
1253 printf("Getting uuid list\n");
1254 rc = get_my_uuids(file);
1255 printf("Write to the file\n");
1256 rc = write_file(file);
1257 rc = close_file(file);
1258 printf("Listing LOV data\n");
1259 rc = get_file_info(filename);
1260 printf("Ping our OSTs\n");
1263 /* the results should match lfs getstripe */
1264 printf("Confirming our results with lfs getstripe\n");
1265 sprintf(sys_cmd, "/usr/bin/lfs getstripe %s/%s", MY_LUSTRE_DIR, TESTFILE);
1268 printf("All done\n");
1272 <para><emphasis role="bold">Makefile for sample application:</emphasis></para>
1274 gcc -g -O2 -Wall -o lustredemo libtest.c -llustreapi
1276 rm -f core lustredemo *.o
1279 rm -f /mnt/lustre/ftest/lustredemo
1280 rm -f /mnt/lustre/ftest/lustre_dummy
1281 cp lustredemo /mnt/lustre/ftest/
1283 <section remap="h5">
1284 <title>See Also</title>
1288 <xref linkend="dbdoclet.50438215_30970"/>
1293 <xref linkend="dbdoclet.50438215_50149"/>
1298 <xref linkend="dbdoclet.50438215_86607"/>
1303 <xref linkend="dbdoclet.50438215_12433"/>