SettingLustreProperties.xml

   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>
   4   <itemizedlist>
   5     <listitem>
   6       <para><xref linkend="dbdoclet.50438215_30970"/></para>
   7     </listitem>
   8     <listitem>
   9       <para><xref linkend="dbdoclet.50438215_50149"/></para>
  10     </listitem>
  11     <listitem>
  12       <para><xref linkend="dbdoclet.50438215_86607"/></para>
  13     </listitem>
  14     <listitem>
  15       <para><xref linkend="dbdoclet.50438215_12433"/></para>
  16     </listitem>
  17     <listitem>
  18       <para><xref linkend="dbdoclet.50438215_15718"/></para>
  19     </listitem>
  20   </itemizedlist>
  21   <note>
  22     <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
  23   </note>
  24   <section xml:id="dbdoclet.50438215_30970">
  25     <title>
  26       <literal>llapi_file_create</literal>
  27     </title>
  28     <para>Use <literal>llapi_file_create</literal> to set Lustre properties for a new file.</para>
  29     <section remap="h5">
  30       <title>Synopsis</title>
  31       <screen>#include &lt;lustre/lustreapi.h&gt;
  32
  33 int llapi_file_create(char *name, long stripe_size, int stripe_offset, int stripe_count, int stripe_pattern);
  34 </screen>
  35     </section>
  36     <section remap="h5">
  37       <title>Description</title>
  38       <para>The <literal>llapi_file_create()</literal> function sets a file descriptor&apos;s Lustre striping information. The file descriptor is then accessed with <literal>open()</literal>.</para>
  39       <informaltable frame="all">
  40         <tgroup cols="2">
  41           <colspec colname="c1" colwidth="50*"/>
  42           <colspec colname="c2" colwidth="50*"/>
  43           <thead>
  44             <row>
  45               <entry>
  46                 <para><emphasis role="bold">Option</emphasis></para>
  47               </entry>
  48               <entry>
  49                 <para><emphasis role="bold">Description</emphasis></para>
  50               </entry>
  51             </row>
  52           </thead>
  53           <tbody>
  54             <row>
  55               <entry>
  56                 <para> <literal>llapi_file_create()</literal></para>
  57               </entry>
  58               <entry>
  59                 <para>If the file already exists, this parameter returns to &apos;<literal>EEXIST</literal>&apos;. If the stripe parameters are invalid, this parameter returns to &apos;<literal>EINVAL</literal>&apos;.</para>
  60               </entry>
  61             </row>
  62             <row>
  63               <entry>
  64                 <para> <literal>stripe_size</literal></para>
  65               </entry>
  66               <entry>
  67                 <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>
  68               </entry>
  69             </row>
  70             <row>
  71               <entry>
  72                 <para> <literal>stripe_offset</literal></para>
  73               </entry>
  74               <entry>
  75                 <para>Indicates the starting OST for this file.</para>
  76               </entry>
  77             </row>
  78             <row>
  79               <entry>
  80                 <para> <literal>stripe_count</literal></para>
  81               </entry>
  82               <entry>
  83                 <para>Indicates the number of OSTs that this file will be striped across.</para>
  84               </entry>
  85             </row>
  86             <row>
  87               <entry>
  88                 <para> <literal>stripe_pattern</literal></para>
  89               </entry>
  90               <entry>
  91                 <para>Indicates the RAID pattern.</para>
  92               </entry>
  93             </row>
  94           </tbody>
  95         </tgroup>
  96       </informaltable>
  97       <note>
  98         <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>
  99       </note>
 100     </section>
 101     <section remap="h5">
 102       <title>Examples</title>
 103       <para>System default size is 4 MB.</para>
 104       <screen>char *tfile = TESTFILE;
 105 int stripe_size = 65536</screen>
 106       <para>To start at default, run:</para>
 107       <screen>int stripe_offset = -1</screen>
 108       <para>To start at the default, run:</para>
 109       <screen>int stripe_count = 1</screen>
 110       <para>To set a single stripe for this example, run:</para>
 111       <screen>int stripe_pattern = 0</screen>
 112       <para>Currently, only RAID 0 is supported.</para>
 113       <screen>int stripe_pattern = 0;
 114 int rc, fd;
 115 rc = llapi_file_create(tfile, stripe_size,stripe_offset, stripe_count,stripe_pattern);</screen>
 116       <para>Result code is inverted, you may return with &apos;<literal>EINVAL</literal>&apos; or an ioctl error.</para>
 117       <screen>if (rc) {
 118 fprintf(stderr,&quot;llapi_file_create failed: %d (%s) 0, rc, strerror(-rc));return -1; }</screen>
 119       <para><literal>llapi_file_create</literal> closes the file descriptor. You must re-open the descriptor. To do this, run:</para>
 120       <screen>fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644); if (fd &lt; 0) \ {
 121 fprintf(stderr, &quot;Can&apos;t open %s file: %s0, tfile,
 122 str-
 123 error(errno));
 124 return -1;
 125 }</screen>
 126     </section>
 127   </section>
 128   <section xml:id="dbdoclet.50438215_50149">
 129     <title>llapi_file_get_stripe</title>
 130     <para>Use <literal>llapi_file_get_stripe</literal> to get striping information for a file or directory on a Lustre file system.</para>
 131     <section remap="h5">
 132       <title>Synopsis</title>
 133       <screen>
 134 #include &lt;lustre/lustreapi.h&gt;
 135
 136 int llapi_file_get_stripe(const char *<emphasis>path</emphasis>, void *<emphasis>lum</emphasis>);</screen>
 137     </section>
 138     <section remap="h5">
 139       <title>Description</title>
 140       <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>
 141       <screen>struct lov_user_md_v1 {
 142 __u32 lmm_magic;
 143 __u32 lmm_pattern;
 144 __u64 lmm_object_id;
 145 __u64 lmm_object_seq;
 146 __u32 lmm_stripe_size;
 147 __u16 lmm_stripe_count;
 148 __u16 lmm_stripe_offset;
 149 struct lov_user_ost_data_v1 lmm_objects[0];
 150 } __attribute__((packed));
 151 struct lov_user_md_v3 {
 152 __u32 lmm_magic;
 153 __u32 lmm_pattern;
 154 __u64 lmm_object_id;
 155 __u64 lmm_object_seq;
 156 __u32 lmm_stripe_size;
 157 __u16 lmm_stripe_count;
 158 __u16 lmm_stripe_offset;
 159 char lmm_pool_name[LOV_MAXPOOLNAME];
 160 struct lov_user_ost_data_v1 lmm_objects[0];
 161 } __attribute__((packed));</screen>
 162       <informaltable frame="all">
 163         <tgroup cols="2">
 164           <colspec colname="c1" colwidth="50*"/>
 165           <colspec colname="c2" colwidth="50*"/>
 166           <thead>
 167             <row>
 168               <entry>
 169                 <para><emphasis role="bold">Option</emphasis></para>
 170               </entry>
 171               <entry>
 172                 <para><emphasis role="bold">Description</emphasis></para>
 173               </entry>
 174             </row>
 175           </thead>
 176           <tbody>
 177             <row>
 178               <entry>
 179                 <para> <literal>lmm_magic</literal></para>
 180               </entry>
 181               <entry>
 182                 <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>
 183               </entry>
 184             </row>
 185             <row>
 186               <entry>
 187                 <para> <literal>lmm_pattern</literal></para>
 188               </entry>
 189               <entry>
 190                 <para>Holds the striping pattern. Only <literal>LOV_PATTERN_RAID0</literal> is possible in this Lustre version.</para>
 191               </entry>
 192             </row>
 193             <row>
 194               <entry>
 195                 <para> <literal>lmm_object_id</literal></para>
 196               </entry>
 197               <entry>
 198                 <para>Holds the MDS object ID.</para>
 199               </entry>
 200             </row>
 201             <row>
 202               <entry>
 203                 <para> <literal>lmm_object_gr</literal></para>
 204               </entry>
 205               <entry>
 206                 <para>Holds the MDS object group.</para>
 207               </entry>
 208             </row>
 209             <row>
 210               <entry>
 211                 <para> <literal>lmm_stripe_size</literal></para>
 212               </entry>
 213               <entry>
 214                 <para>Holds the stripe size in bytes.</para>
 215               </entry>
 216             </row>
 217             <row>
 218               <entry>
 219                 <para> <literal>lmm_stripe_count</literal></para>
 220               </entry>
 221               <entry>
 222                 <para>Holds the number of OSTs over which the file is striped.</para>
 223               </entry>
 224             </row>
 225             <row>
 226               <entry>
 227                 <para> <literal>lmm_stripe_offset</literal></para>
 228               </entry>
 229               <entry>
 230                 <para>Holds the OST index from which the file starts.</para>
 231               </entry>
 232             </row>
 233             <row>
 234               <entry>
 235                 <para> <literal>lmm_pool_name</literal></para>
 236               </entry>
 237               <entry>
 238                 <para>Holds the OST pool name to which the file belongs.</para>
 239               </entry>
 240             </row>
 241             <row>
 242               <entry>
 243                 <para> <literal>lmm_objects</literal></para>
 244               </entry>
 245               <entry>
 246                 <para>An array of <literal>lmm_stripe_count</literal> members containing per OST file information in</para>
 247                 <para>the following format:</para>
 248                 <screen>struct lov_user_ost_data_v1 {
 249                 __u64 l_object_id;
 250                 __u64 l_object_seq;
 251                 __u32 l_ost_gen;
 252                 __u32 l_ost_idx;
 253                 } __attribute__((packed));</screen>
 254               </entry>
 255             </row>
 256             <row>
 257               <entry>
 258                 <para> <literal>l_object_id</literal></para>
 259               </entry>
 260               <entry>
 261                 <para>Holds the OST&apos;s object ID.</para>
 262               </entry>
 263             </row>
 264             <row>
 265               <entry>
 266                 <para> <literal>l_object_seq</literal></para>
 267               </entry>
 268               <entry>
 269                 <para>Holds the OST&apos;s object group.</para>
 270               </entry>
 271             </row>
 272             <row>
 273               <entry>
 274                 <para> <literal>l_ost_gen</literal></para>
 275               </entry>
 276               <entry>
 277                 <para>Holds the OST&apos;s index generation.</para>
 278               </entry>
 279             </row>
 280             <row>
 281               <entry>
 282                 <para> <literal>l_ost_idx</literal></para>
 283               </entry>
 284               <entry>
 285                 <para>Holds the OST&apos;s index in LOV.</para>
 286               </entry>
 287             </row>
 288           </tbody>
 289         </tgroup>
 290       </informaltable>
 291     </section>
 292     <section remap="h5">
 293       <title>Return Values</title>
 294       <para><literal>llapi_file_get_stripe()</literal> returns:</para>
 295       <para><literal>0</literal> On success</para>
 296       <para><literal>!= 0</literal> On failure, <literal>errno</literal> is set appropriately</para>
 297     </section>
 298     <section remap="h5">
 299       <title>Errors</title>
 300       <informaltable frame="all">
 301         <tgroup cols="2">
 302           <colspec colname="c1" colwidth="50*"/>
 303           <colspec colname="c2" colwidth="50*"/>
 304           <thead>
 305             <row>
 306               <entry>
 307                 <para><emphasis role="bold">Errors</emphasis></para>
 308               </entry>
 309               <entry>
 310                 <para><emphasis role="bold">Description</emphasis></para>
 311               </entry>
 312             </row>
 313           </thead>
 314           <tbody>
 315             <row>
 316               <entry>
 317                 <para> <literal>ENOMEM</literal></para>
 318               </entry>
 319               <entry>
 320                 <para>Failed to allocate memory</para>
 321               </entry>
 322             </row>
 323             <row>
 324               <entry>
 325                 <para> <literal>ENAMETOOLONG</literal></para>
 326               </entry>
 327               <entry>
 328                 <para>Path was too long</para>
 329               </entry>
 330             </row>
 331             <row>
 332               <entry>
 333                 <para> <literal>ENOENT</literal></para>
 334               </entry>
 335               <entry>
 336                 <para>Path does not point to a file or directory</para>
 337               </entry>
 338             </row>
 339             <row>
 340               <entry>
 341                 <para> <literal>ENOTTY</literal></para>
 342               </entry>
 343               <entry>
 344                 <para>Path does not point to a Lustre file system</para>
 345               </entry>
 346             </row>
 347             <row>
 348               <entry>
 349                 <para> <literal>EFAULT</literal></para>
 350               </entry>
 351               <entry>
 352                 <para>Memory region pointed by lum is not properly mapped</para>
 353               </entry>
 354             </row>
 355           </tbody>
 356         </tgroup>
 357       </informaltable>
 358     </section>
 359     <section remap="h5">
 360       <title>Examples</title>
 361       <programlisting>
 362 #include &lt;stdio.h&gt;
 363 #include &lt;stdlib.h&gt;
 364 #include &lt;errno.h&gt;
 365 #include &lt;lustre/lustreapi.h&gt;
 366
 367 static inline int maxint(int a, int b)
 368 {
 369         return a &gt; b ? a : b;
 370 }
 371 static void *alloc_lum()
 372 {
 373         int v1, v3, join;
 374         v1 = sizeof(struct lov_user_md_v1) +
 375                 LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
 376         v3 = sizeof(struct lov_user_md_v3) +
 377                 LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
 378         return malloc(maxint(v1, v3));
 379 }
 380 int main(int argc, char** argv)
 381 {
 382         struct lov_user_md *lum_file = NULL;
 383         int rc;
 384         int lum_size;
 385         if (argc != 2) {
 386                 fprintf(stderr, &quot;Usage: %s &lt;filename&gt;\n&quot;, argv[0]);
 387                 return 1;
 388         }
 389         lum_file = alloc_lum();
 390         if (lum_file == NULL) {
 391                 rc = ENOMEM;
 392                 goto cleanup;
 393         }
 394         rc = llapi_file_get_stripe(argv[1], lum_file);
 395         if (rc) {
 396                 rc = errno;
 397                 goto cleanup;
 398         }
 399         /* stripe_size stripe_count */
 400         printf(&quot;%d %d\n&quot;,
 401                         lum_file-&gt;lmm_stripe_size,
 402                         lum_file-&gt;lmm_stripe_count);
 403 cleanup:
 404         if (lum_file != NULL)
 405                 free(lum_file);
 406         return rc;
 407 }
 408 </programlisting>
 409     </section>
 410   </section>
 411   <section xml:id="dbdoclet.50438215_86607">
 412     <title>
 413       <literal>llapi_file_open</literal>
 414     </title>
 415     <para>The <literal>llapi_file_open</literal> command opens (or creates) a file or device on a Lustre filesystem.</para>
 416     <section remap="h5">
 417       <title>Synopsis</title>
 418       <screen>#include &lt;lustre/lustreapi.h&gt;
 419 int llapi_file_open(const char *<emphasis>name</emphasis>, int <emphasis>flags</emphasis>, int <emphasis>mode</emphasis>,
 420    unsigned long long <emphasis>stripe_size</emphasis>, int <emphasis>stripe_offset</emphasis>,
 421    int <emphasis>stripe_count</emphasis>, int <emphasis>stripe_pattern</emphasis>);
 422 int llapi_file_create(const char *<emphasis>name</emphasis>, unsigned long long <emphasis>stripe_size</emphasis>,
 423    int <emphasis>stripe_offset</emphasis>, int <emphasis>stripe_count</emphasis>,
 424    int <emphasis>stripe_pattern</emphasis>);
 425 </screen>
 426     </section>
 427     <section remap="h5">
 428       <title>Description</title>
 429       <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>
 430       <para><literal>llapi_file_open()</literal> opens a file with a given name on a Lustre filesystem.</para>
 431       <informaltable frame="all">
 432         <tgroup cols="2">
 433           <colspec colname="c1" colwidth="50*"/>
 434           <colspec colname="c2" colwidth="50*"/>
 435           <thead>
 436             <row>
 437               <entry>
 438                 <para><emphasis role="bold">Option</emphasis></para>
 439               </entry>
 440               <entry>
 441                 <para><emphasis role="bold">Description</emphasis></para>
 442               </entry>
 443             </row>
 444           </thead>
 445           <tbody>
 446             <row>
 447               <entry>
 448                 <para> <literal>flags</literal></para>
 449               </entry>
 450               <entry>
 451                 <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>
 452               </entry>
 453             </row>
 454             <row>
 455               <entry>
 456                 <para> <literal>mode</literal></para>
 457               </entry>
 458               <entry>
 459                 <para>Specifies the permission bits to be used for a new file when <literal>O_CREAT</literal> is used.</para>
 460               </entry>
 461             </row>
 462             <row>
 463               <entry>
 464                 <para> <literal>stripe_size</literal></para>
 465               </entry>
 466               <entry>
 467                 <para>Specifies stripe size (in bytes). Should be multiple of 64 KB, not exceeding 4 GB.</para>
 468               </entry>
 469             </row>
 470             <row>
 471               <entry>
 472                 <para> <literal>stripe_offset</literal></para>
 473               </entry>
 474               <entry>
 475                 <para>Specifies an OST index from which the file should start. The default value is -1.</para>
 476               </entry>
 477             </row>
 478             <row>
 479               <entry>
 480                 <para> <literal>stripe_count</literal></para>
 481               </entry>
 482               <entry>
 483                 <para>Specifies the number of OSTs to stripe the file across. The default value is -1.</para>
 484               </entry>
 485             </row>
 486             <row>
 487               <entry>
 488                 <para> <literal>stripe_pattern</literal></para>
 489               </entry>
 490               <entry>
 491                 <para>Specifies the striping pattern. In this version of Lustre, only <literal>LOV_PATTERN_RAID0</literal> is available. The default value is 0.</para>
 492               </entry>
 493             </row>
 494           </tbody>
 495         </tgroup>
 496       </informaltable>
 497     </section>
 498     <section remap="h5">
 499       <title>Return Values</title>
 500       <para><literal>llapi_file_open()</literal> and <literal>llapi_file_create()</literal> return:</para>
 501       <para><literal>&gt;=0</literal> On success, for <literal>llapi_file_open</literal> the return value is a file descriptor</para>
 502       <para><literal>&lt;0</literal> On failure, the absolute value is an error code</para>
 503     </section>
 504     <section remap="h5">
 505       <title>Errors</title>
 506       <informaltable frame="all">
 507         <tgroup cols="2">
 508           <colspec colname="c1" colwidth="50*"/>
 509           <colspec colname="c2" colwidth="50*"/>
 510           <thead>
 511             <row>
 512               <entry>
 513                 <para><emphasis role="bold">Errors</emphasis></para>
 514               </entry>
 515               <entry>
 516                 <para><emphasis role="bold">Description</emphasis></para>
 517               </entry>
 518             </row>
 519           </thead>
 520           <tbody>
 521             <row>
 522               <entry>
 523                 <para> <literal>EINVAL</literal></para>
 524               </entry>
 525               <entry>
 526                 <para><literal>stripe_size</literal> or <literal>stripe_offset</literal> or <literal>stripe_count</literal> or <literal>stripe_pattern</literal> is invalid.</para>
 527               </entry>
 528             </row>
 529             <row>
 530               <entry>
 531                 <para> <literal>EEXIST</literal></para>
 532               </entry>
 533               <entry>
 534                 <para>Striping information has already been set and cannot be altered; <literal>name</literal> already exists.</para>
 535               </entry>
 536             </row>
 537             <row>
 538               <entry>
 539                 <para> <literal>EALREADY</literal></para>
 540               </entry>
 541               <entry>
 542                 <para>Striping information has already been set and cannot be altered</para>
 543               </entry>
 544             </row>
 545             <row>
 546               <entry>
 547                 <para> <literal>ENOTTY</literal></para>
 548               </entry>
 549               <entry>
 550                 <para> <literal>name</literal> may not point to a Lustre filesystem.</para>
 551               </entry>
 552             </row>
 553           </tbody>
 554         </tgroup>
 555       </informaltable>
 556     </section>
 557     <section remap="h5">
 558       <title>Example</title>
 559       <programlisting>
 560 #include &lt;stdio.h&gt;
 561 #include &lt;lustre/lustreapi.h&gt;
 562
 563 int main(int argc, char *argv[])
 564 {
 565         int rc;
 566         if (argc != 2)
 567                 return -1;
 568         rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
 569         if (rc &lt; 0) {
 570                 fprintf(stderr, &quot;file creation has failed, %s\n&quot;,         strerror(-rc));
 571                 return -1;
 572         }
 573         printf(&quot;%s with stripe size 1048576, striped across 2 OSTs,&quot;
 574                         &quot; has been created!\n&quot;, argv[1]);
 575         return 0;
 576 }
 577 </programlisting>
 578     </section>
 579   </section>
 580   <section xml:id="dbdoclet.50438215_12433">
 581     <title>
 582       <literal>llapi_quotactl</literal>
 583     </title>
 584     <para>Use <literal>llapi_quotact</literal>l to manipulate disk quotas on a Lustre file system.</para>
 585     <section remap="h5">
 586       <title>Synopsis</title>
 587       <screen>#include &lt;lustre/lustreapi.h&gt;
 588 int llapi_quotactl(char&quot; &quot; *mnt,&quot; &quot; struct if_quotactl&quot; &quot; *qctl)
 589
 590 struct if_quotactl {
 591         __u32                   qc_cmd;
 592         __u32                   qc_type;
 593         __u32                   qc_id;
 594         __u32                   qc_stat;
 595         struct obd_dqinfo       qc_dqinfo;
 596         struct obd_dqblk        qc_dqblk;
 597         char                    obd_type[16];
 598         struct obd_uuid         obd_uuid;
 599 };
 600 struct obd_dqblk {
 601         __u64 dqb_bhardlimit;
 602         __u64 dqb_bsoftlimit;
 603         __u64 dqb_curspace;
 604         __u64 dqb_ihardlimit;
 605         __u64 dqb_isoftlimit;
 606         __u64 dqb_curinodes;
 607         __u64 dqb_btime;
 608         __u64 dqb_itime;
 609         __u32 dqb_valid;
 610         __u32 padding;
 611 };
 612 struct obd_dqinfo {
 613         __u64 dqi_bgrace;
 614         __u64 dqi_igrace;
 615         __u32 dqi_flags;
 616         __u32 dqi_valid;
 617 };
 618 struct obd_uuid {
 619         char uuid[40];
 620 };</screen>
 621     </section>
 622     <section remap="h5">
 623       <title>Description</title>
 624       <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>
 625       <informaltable frame="all">
 626         <tgroup cols="2">
 627           <colspec colname="c1" colwidth="50*"/>
 628           <colspec colname="c2" colwidth="50*"/>
 629           <thead>
 630             <row>
 631               <entry>
 632                 <para><emphasis role="bold">Option</emphasis></para>
 633               </entry>
 634               <entry>
 635                 <para><emphasis role="bold">Description</emphasis></para>
 636               </entry>
 637             </row>
 638           </thead>
 639           <tbody>
 640             <row>
 641               <entry>
 642                 <para> <literal>LUSTRE_Q_QUOTAON</literal></para>
 643               </entry>
 644               <entry>
 645                 <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>
 646               </entry>
 647             </row>
 648             <row>
 649               <entry>
 650                 <para> <literal>LUSTRE_Q_QUOTAOFF</literal></para>
 651               </entry>
 652               <entry>
 653                 <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>
 654               </entry>
 655             </row>
 656             <row>
 657               <entry>
 658                 <para> <literal>LUSTRE_Q_GETQUOTA</literal></para>
 659               </entry>
 660               <entry>
 661                 <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>
 662               </entry>
 663             </row>
 664             <row>
 665               <entry>
 666                 <para> <literal>LUSTRE_Q_SETQUOTA</literal></para>
 667               </entry>
 668               <entry>
 669                 <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>
 670               </entry>
 671             </row>
 672             <row>
 673               <entry>
 674                 <para> <literal>LUSTRE_Q_GETINFO</literal></para>
 675               </entry>
 676               <entry>
 677                 <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>
 678               </entry>
 679             </row>
 680             <row>
 681               <entry>
 682                 <para> <literal>LUSTRE_Q_SETINFO</literal></para>
 683               </entry>
 684               <entry>
 685                 <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>
 686               </entry>
 687             </row>
 688           </tbody>
 689         </tgroup>
 690       </informaltable>
 691     </section>
 692     <section remap="h5">
 693       <title>Return Values</title>
 694       <para><literal>llapi_quotactl()</literal> returns:</para>
 695       <para><literal>0</literal> On success</para>
 696       <para><literal> -1 </literal> On failure and sets error number (<literal>errno</literal>) to indicate the error</para>
 697     </section>
 698     <section remap="h5">
 699       <title>Errors</title>
 700       <para><literal>llapi_quotactl</literal> errors are described below.</para>
 701       <informaltable frame="all">
 702         <tgroup cols="2">
 703           <colspec colname="c1" colwidth="50*"/>
 704           <colspec colname="c2" colwidth="50*"/>
 705           <thead>
 706             <row>
 707               <entry>
 708                 <para><emphasis role="bold">Errors</emphasis></para>
 709               </entry>
 710               <entry>
 711                 <para><emphasis role="bold">Description</emphasis></para>
 712               </entry>
 713             </row>
 714           </thead>
 715           <tbody>
 716             <row>
 717               <entry>
 718                 <para> <literal>EFAULT</literal></para>
 719               </entry>
 720               <entry>
 721                 <para><emphasis>qctl</emphasis> is invalid.</para>
 722               </entry>
 723             </row>
 724             <row>
 725               <entry>
 726                 <para> <literal>ENOSYS</literal></para>
 727               </entry>
 728               <entry>
 729                 <para>Kernel or Lustre modules have not been compiled with the <literal>QUOTA</literal> option.</para>
 730               </entry>
 731             </row>
 732             <row>
 733               <entry>
 734                 <para> <literal>ENOMEM</literal></para>
 735               </entry>
 736               <entry>
 737                 <para>Insufficient memory to complete operation.</para>
 738               </entry>
 739             </row>
 740             <row>
 741               <entry>
 742                 <para> <literal>ENOTTY</literal></para>
 743               </entry>
 744               <entry>
 745                 <para> <emphasis>qc_cmd</emphasis> is invalid.</para>
 746               </entry>
 747             </row>
 748             <row>
 749               <entry>
 750                 <para> <literal>EBUSY</literal></para>
 751               </entry>
 752               <entry>
 753                 <para>Cannot process during quotacheck.</para>
 754               </entry>
 755             </row>
 756             <row>
 757               <entry>
 758                 <para> <literal>ENOENT</literal></para>
 759               </entry>
 760               <entry>
 761                 <para> <emphasis>uuid</emphasis> does not correspond to OBD or <emphasis>mnt</emphasis> does not exist.</para>
 762               </entry>
 763             </row>
 764             <row>
 765               <entry>
 766                 <para> <literal>EPERM</literal></para>
 767               </entry>
 768               <entry>
 769                 <para>The call is privileged and the caller is not the super user.</para>
 770               </entry>
 771             </row>
 772             <row>
 773               <entry>
 774                 <para> <literal>ESRCH</literal></para>
 775               </entry>
 776               <entry>
 777                 <para>No disk quota is found for the indicated user. Quotas have not been turned on for this file system.</para>
 778               </entry>
 779             </row>
 780           </tbody>
 781         </tgroup>
 782       </informaltable>
 783     </section>
 784   </section>
 785   <section xml:id="dbdoclet.50438215_15718">
 786     <title>
 787       <literal>llapi_path2fid</literal>
 788     </title>
 789     <para>Use <literal>llapi_path2fid</literal> to get the FID from the pathname.</para>
 790     <section remap="h5">
 791       <title>Synopsis</title>
 792       <screen>#include &lt;lustre/lustreapi.h&gt;
 793
 794 int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid, unsigned long *ver)</screen>
 795     </section>
 796     <section remap="h5">
 797       <title>Description</title>
 798       <para>The <literal>llapi_path2fid</literal> function returns the FID (sequence : object ID : version) for the pathname.</para>
 799     </section>
 800     <section remap="h5">
 801       <title>Return Values</title>
 802       <para><literal>llapi_path2fid</literal> returns:</para>
 803       <para><literal>0</literal> On success</para>
 804       <para>non-zero value On failure</para>
 805     </section>
 806   </section>
 807   <section xml:id="dbdoclet.50438215_marker-1297700">
 808     <title>Example Using the <literal>llapi</literal> Library</title>
 809     <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>
 810     <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>
 811     <para><emphasis role="bold">A simple C program to demonstrate striping API - libtest.c</emphasis></para>
 812     <programlisting>
 813 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
 814  * vim:expandtab:shiftwidth=8:tabstop=8:
 815  *
 816  * lustredemo - a simple example of lustreapi functions
 817  */
 818 #include &lt;stdio.h&gt;
 819 #include &lt;fcntl.h&gt;
 820 #include &lt;dirent.h&gt;
 821 #include &lt;errno.h&gt;
 822 #include &lt;stdlib.h&gt;
 823 #include &lt;lustre/lustreapi.h&gt;
 824 #define MAX_OSTS 1024
 825 #define LOV_EA_SIZE(lum, num) (sizeof(*lum) + num * sizeof(*lum-&gt;lmm_objects))
 826 #define LOV_EA_MAX(lum) LOV_EA_SIZE(lum, MAX_OSTS)
 827
 828 /*
 829  * This program provides crude examples of using the lustreapi API functions
 830  */
 831 /* Change these definitions to suit */
 832
 833 #define TESTDIR &quot;/tmp&quot;           /* Results directory */
 834 #define TESTFILE &quot;lustre_dummy&quot;  /* Name for the file we create/destroy */
 835 #define FILESIZE 262144                    /* Size of the file in words */
 836 #define DUMWORD &quot;DEADBEEF&quot;       /* Dummy word used to fill files */
 837 #define MY_STRIPE_WIDTH 2                  /* Set this to the number of OST required */
 838 #define MY_LUSTRE_DIR &quot;/mnt/lustre/ftest&quot;
 839
 840 int close_file(int fd)
 841 {
 842         if (close(fd) &lt; 0) {
 843                 fprintf(stderr, &quot;File close failed: %d (%s)\n&quot;, errno, strerror(errno));
 844                 return -1;
 845         }
 846         return 0;
 847 }
 848
 849 int write_file(int fd)
 850 {
 851         char *stng =  DUMWORD;
 852         int cnt = 0;
 853
 854         for( cnt = 0; cnt &lt; FILESIZE; cnt++) {
 855                 write(fd, stng, sizeof(stng));
 856         }
 857         return 0;
 858 }
 859 /* Open a file, set a specific stripe count, size and starting OST
 860  *    Adjust the parameters to suit */
 861 int open_stripe_file()
 862 {
 863         char *tfile = TESTFILE;
 864         int stripe_size = 65536;    /* System default is 4M */
 865         int stripe_offset = -1;     /* Start at default */
 866         int stripe_count = MY_STRIPE_WIDTH;  /*Single stripe for this demo*/
 867         int stripe_pattern = 0;     /* only RAID 0 at this time */
 868         int rc, fd;
 869
 870         rc = llapi_file_create(tfile,
 871                         stripe_size,stripe_offset,stripe_count,stripe_pattern);
 872         /* result code is inverted, we may return -EINVAL or an ioctl error.
 873          * We borrow an error message from sanity.c
 874          */
 875         if (rc) {
 876                 fprintf(stderr,&quot;llapi_file_create failed: %d (%s) \n&quot;, rc, strerror(-rc));
 877                 return -1;
 878         }
 879         /* llapi_file_create closes the file descriptor, we must re-open */
 880         fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644);
 881         if (fd &lt; 0) {
 882                 fprintf(stderr, &quot;Can't open %s file: %d (%s)\n&quot;, tfile, errno, strerror(errno));
 883                 return -1;
 884         }
 885         return fd;
 886 }
 887
 888 /* output a list of uuids for this file */
 889 int get_my_uuids(int fd)
 890 {
 891         struct obd_uuid uuids[1024], *uuidp;        /* Output var */
 892         int obdcount = 1024;
 893         int rc,i;
 894
 895         rc = llapi_lov_get_uuids(fd, uuids, &amp;obdcount);
 896         if (rc != 0) {
 897                 fprintf(stderr, &quot;get uuids failed: %d (%s)\n&quot;,errno, strerror(errno));
 898         }
 899         printf(&quot;This file system has %d obds\n&quot;, obdcount);
 900         for (i = 0, uuidp = uuids; i &lt; obdcount; i++, uuidp++) {
 901                 printf(&quot;UUID %d is %s\n&quot;,i, uuidp-&gt;uuid);
 902         }
 903         return 0;
 904 }
 905
 906 /* Print out some LOV attributes. List our objects */
 907 int get_file_info(char *path)
 908 {
 909
 910         struct lov_user_md *lump;
 911         int rc;
 912         int i;
 913
 914         lump = malloc(LOV_EA_MAX(lump));
 915         if (lump == NULL) {
 916                 return -1;
 917         }
 918
 919         rc = llapi_file_get_stripe(path, lump);
 920
 921         if (rc != 0) {
 922                 fprintf(stderr, &quot;get_stripe failed: %d (%s)\n&quot;,errno, strerror(errno));
 923                 return -1;
 924         }
 925
 926         printf(&quot;Lov magic %u\n&quot;, lump-&gt;lmm_magic);
 927         printf(&quot;Lov pattern %u\n&quot;, lump-&gt;lmm_pattern);
 928         printf(&quot;Lov object id %llu\n&quot;, lump-&gt;lmm_object_id);
 929         printf(&quot;Lov stripe size %u\n&quot;, lump-&gt;lmm_stripe_size);
 930         printf(&quot;Lov stripe count %hu\n&quot;, lump-&gt;lmm_stripe_count);
 931         printf(&quot;Lov stripe offset %u\n&quot;, lump-&gt;lmm_stripe_offset);
 932         for (i = 0; i &lt; lump-&gt;lmm_stripe_count; i++) {
 933                 printf(&quot;Object index %d Objid %llu\n&quot;, lump-&gt;lmm_objects[i].l_ost_idx, lump-&gt;lmm_objects[i].l_object_id);
 934         }
 935
 936         free(lump);
 937         return rc;
 938
 939 }
 940
 941 /* Ping all OSTs that belong to this filesystem */
 942 int ping_osts()
 943 {
 944         DIR *dir;
 945         struct dirent *d;
 946         char osc_dir[100];
 947         int rc;
 948
 949         sprintf(osc_dir, &quot;/proc/fs/lustre/osc&quot;);
 950         dir = opendir(osc_dir);
 951         if (dir == NULL) {
 952                 printf(&quot;Can't open dir\n&quot;);
 953                 return -1;
 954         }
 955         while((d = readdir(dir)) != NULL) {
 956                 if ( d-&gt;d_type == DT_DIR ) {
 957                         if (! strncmp(d-&gt;d_name, &quot;OSC&quot;, 3)) {
 958                                 printf(&quot;Pinging OSC %s &quot;, d-&gt;d_name);
 959                                 rc = llapi_ping(&quot;osc&quot;, d-&gt;d_name);
 960                                 if (rc) {
 961                                         printf(&quot;  bad\n&quot;);
 962                                 } else {
 963                                         printf(&quot;  good\n&quot;);
 964                                 }
 965                         }
 966                 }
 967         }
 968         return 0;
 969
 970 }
 971
 972 int main()
 973 {
 974         int file;
 975         int rc;
 976         char filename[100];
 977         char sys_cmd[100];
 978
 979         sprintf(filename, &quot;%s/%s&quot;,MY_LUSTRE_DIR, TESTFILE);
 980
 981         printf(&quot;Open a file with striping\n&quot;);
 982         file = open_stripe_file();
 983         if ( file &lt; 0 ) {
 984                 printf(&quot;Exiting\n&quot;);
 985                 exit(1);
 986         }
 987         printf(&quot;Getting uuid list\n&quot;);
 988         rc = get_my_uuids(file);
 989         printf(&quot;Write to the file\n&quot;);
 990         rc = write_file(file);
 991         rc = close_file(file);
 992         printf(&quot;Listing LOV data\n&quot;);
 993         rc = get_file_info(filename);
 994         printf(&quot;Ping our OSTs\n&quot;);
 995         rc = ping_osts();
 996
 997         /* the results should match lfs getstripe */
 998         printf(&quot;Confirming our results with lfs getstripe\n&quot;);
 999         sprintf(sys_cmd, &quot;/usr/bin/lfs getstripe %s/%s&quot;, MY_LUSTRE_DIR, TESTFILE);
1000         system(sys_cmd);
1001
1002         printf(&quot;All done\n&quot;);
1003         exit(rc);
1004 }
1005 </programlisting>
1006     <para><emphasis role="bold">Makefile for sample application:</emphasis></para>
1007     <screen>
1008 gcc -g -O2 -Wall -o lustredemo libtest.c -llustreapi
1009 clean:
1010 rm -f core lustredemo *.o
1011 run:
1012 make
1013 rm -f /mnt/lustre/ftest/lustredemo
1014 rm -f /mnt/lustre/ftest/lustre_dummy
1015 cp lustredemo /mnt/lustre/ftest/
1016 </screen>
1017     <section remap="h5">
1018       <title>See Also</title>
1019       <itemizedlist>
1020         <listitem>
1021           <para>
1022             <xref linkend="dbdoclet.50438215_30970"/>
1023     </para>
1024         </listitem>
1025         <listitem>
1026           <para>
1027             <xref linkend="dbdoclet.50438215_50149"/>
1028     </para>
1029         </listitem>
1030         <listitem>
1031           <para>
1032             <xref linkend="dbdoclet.50438215_86607"/>
1033     </para>
1034         </listitem>
1035         <listitem>
1036           <para>
1037             <xref linkend="dbdoclet.50438215_12433"/>
1038     </para>
1039         </listitem>
1040       </itemizedlist>
1041     </section>
1042   </section>
1043 </chapter>