SettingLustreProperties.xml

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