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   <title xml:id="settinglustreproperties.title">Setting Lustre Properties in a C Program (<literal>llapi</literal>)</title>
   4   <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>
   5   <itemizedlist>
   6     <listitem>
   7       <para><xref linkend="dbdoclet.50438215_30970"/></para>
   8     </listitem>
   9     <listitem>
  10       <para><xref linkend="dbdoclet.50438215_50149"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="dbdoclet.50438215_86607"/></para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="dbdoclet.50438215_12433"/></para>
  17     </listitem>
  18     <listitem>
  19       <para><xref linkend="dbdoclet.50438215_15718"/></para>
  20     </listitem>
  21   </itemizedlist>
  22   <note>
  23     <para>Lustre programming interface man pages are found in the <literal>lustre/doc</literal> folder.</para>
  24   </note>
  25   <section xml:id="dbdoclet.50438215_30970">
  26     <title>
  27       <literal>llapi_file_create</literal>
  28     </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>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>
 420       <literal>llapi_file_open</literal>
 421     </title>
 422     <para>The <literal>llapi_file_open</literal> command opens (or creates) a file or device on a Lustre filesystem.</para>
 423     <section remap="h5">
 424       <title>Synopsis</title>
 425       <screen>#include &lt;sys/types.h&gt;
 426 #include &lt;sys/stat.h&gt;
 427 #include &lt;fcntl.h&gt;
 428 #include &lt;liblustre.h&gt;
 429 #include &lt;lustre/lustre_idl.h&gt;
 430 #include &lt;lustre/liblustreapi.h&gt;
 431 #include &lt;lustre/lustre_user.h&gt;
 432 int llapi_file_open(const char *<emphasis>name</emphasis>, int <emphasis>flags</emphasis>, int <emphasis>mode</emphasis>,
 433    unsigned long long <emphasis>stripe_size</emphasis>, int <emphasis>stripe_offset</emphasis>,
 434    int <emphasis>stripe_count</emphasis>, int <emphasis>stripe_pattern</emphasis>);
 435 int llapi_file_create(const char *<emphasis>name</emphasis>, unsigned long long <emphasis>stripe_size</emphasis>,
 436    int <emphasis>stripe_offset</emphasis>, int <emphasis>stripe_count</emphasis>,
 437    int <emphasis>stripe_pattern</emphasis>);
 438 </screen>
 439     </section>
 440     <section remap="h5">
 441       <title>Description</title>
 442       <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>
 443       <para><literal>llapi_file_open()</literal> opens a file with a given name on a Lustre filesystem.</para>
 444       <informaltable frame="all">
 445         <tgroup cols="2">
 446           <colspec colname="c1" colwidth="50*"/>
 447           <colspec colname="c2" colwidth="50*"/>
 448           <thead>
 449             <row>
 450               <entry>
 451                 <para><emphasis role="bold">Option</emphasis></para>
 452               </entry>
 453               <entry>
 454                 <para><emphasis role="bold">Description</emphasis></para>
 455               </entry>
 456             </row>
 457           </thead>
 458           <tbody>
 459             <row>
 460               <entry>
 461                 <para> <literal>flags</literal></para>
 462               </entry>
 463               <entry>
 464                 <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>
 465               </entry>
 466             </row>
 467             <row>
 468               <entry>
 469                 <para> <literal>mode</literal></para>
 470               </entry>
 471               <entry>
 472                 <para>Specifies the permission bits to be used for a new file when <literal>O_CREAT</literal> is used.</para>
 473               </entry>
 474             </row>
 475             <row>
 476               <entry>
 477                 <para> <literal>stripe_size</literal></para>
 478               </entry>
 479               <entry>
 480                 <para>Specifies stripe size (in bytes). Should be multiple of 64 KB, not exceeding 4 GB.</para>
 481               </entry>
 482             </row>
 483             <row>
 484               <entry>
 485                 <para> <literal>stripe_offset</literal></para>
 486               </entry>
 487               <entry>
 488                 <para>Specifies an OST index from which the file should start. The default value is -1.</para>
 489               </entry>
 490             </row>
 491             <row>
 492               <entry>
 493                 <para> <literal>stripe_count</literal></para>
 494               </entry>
 495               <entry>
 496                 <para>Specifies the number of OSTs to stripe the file across. The default value is -1.</para>
 497               </entry>
 498             </row>
 499             <row>
 500               <entry>
 501                 <para> <literal>stripe_pattern</literal></para>
 502               </entry>
 503               <entry>
 504                 <para>Specifies the striping pattern. In this version of Lustre, only <literal>LOV_PATTERN_RAID0</literal> is available. The default value is 0.</para>
 505               </entry>
 506             </row>
 507           </tbody>
 508         </tgroup>
 509       </informaltable>
 510     </section>
 511     <section remap="h5">
 512       <title>Return Values</title>
 513       <para><literal>llapi_file_open()</literal> and <literal>llapi_file_create()</literal> return:</para>
 514       <para><literal>&gt;=0</literal> On success, for <literal>llapi_file_open</literal> the return value is a file descriptor</para>
 515       <para><literal>&lt;0</literal> On failure, the absolute value is an error code</para>
 516     </section>
 517     <section remap="h5">
 518       <title>Errors</title>
 519       <informaltable frame="all">
 520         <tgroup cols="2">
 521           <colspec colname="c1" colwidth="50*"/>
 522           <colspec colname="c2" colwidth="50*"/>
 523           <thead>
 524             <row>
 525               <entry>
 526                 <para><emphasis role="bold">Errors</emphasis></para>
 527               </entry>
 528               <entry>
 529                 <para><emphasis role="bold">Description</emphasis></para>
 530               </entry>
 531             </row>
 532           </thead>
 533           <tbody>
 534             <row>
 535               <entry>
 536                 <para> <literal>EINVAL</literal></para>
 537               </entry>
 538               <entry>
 539                 <para><literal>stripe_size</literal> or <literal>stripe_offset</literal> or <literal>stripe_count</literal> or <literal>stripe_pattern</literal> is invalid.</para>
 540               </entry>
 541             </row>
 542             <row>
 543               <entry>
 544                 <para> <literal>EEXIST</literal></para>
 545               </entry>
 546               <entry>
 547                 <para> triping information has already been set and cannot be altered; <literal>name</literal> already exists.</para>
 548               </entry>
 549             </row>
 550             <row>
 551               <entry>
 552                 <para> <literal>EALREADY</literal></para>
 553               </entry>
 554               <entry>
 555                 <para>Striping information has already been set and cannot be altered</para>
 556               </entry>
 557             </row>
 558             <row>
 559               <entry>
 560                 <para> <literal>ENOTTY</literal></para>
 561               </entry>
 562               <entry>
 563                 <para> <literal>name</literal> may not point to a Lustre filesystem.</para>
 564               </entry>
 565             </row>
 566           </tbody>
 567         </tgroup>
 568       </informaltable>
 569     </section>
 570     <section remap="h5">
 571       <title>Example</title>
 572       <screen>#include &lt;sys/types.h&gt;
 573 #include &lt;sys/stat.h&gt;
 574 #include &lt;fcntl.h&gt;
 575 #include &lt;errno.h&gt;
 576 #include &lt;stdio.h&gt;
 577 #include &lt;liblustre.h&gt;
 578 #include &lt;lustre/lustre_idl.h&gt;
 579 #include &lt;lustre/liblustreapi.h&gt;
 580 #include &lt;lustre/lustre_user.h&gt;
 581 int main(int argc, char *argv[])
 582 {
 583    int rc;
 584    if (argc != 2)
 585            return -1;
 586    rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
 587    if (rc &lt; 0) {
 588            fprintf(stderr, &quot;file creation has failed, %s\n&quot;,         strerror(-rc));
 589            return -1;
 590    }
 591    printf(&quot;%s with stripe size 1048576, striped across 2 OSTs,&quot;
 592            &quot; has been created!\n&quot;, argv[1]);
 593    return 0;
 594 }</screen>
 595     </section>
 596   </section>
 597   <section xml:id="dbdoclet.50438215_12433">
 598     <title>
 599       <literal>llapi_quotactl</literal>
 600     </title>
 601     <para>Use <literal>llapi_quotact</literal>l to manipulate disk quotas on a Lustre file system.</para>
 602     <section remap="h5">
 603       <title>Synopsis</title>
 604       <screen>#include &lt;liblustre.h&gt;
 605 #include &lt;lustre/lustre_idl.h&gt;
 606 #include &lt;lustre/liblustreapi.h&gt;
 607 #include &lt;lustre/lustre_user.h&gt;
 608 int llapi_quotactl(char&quot; &quot; *mnt,&quot; &quot; struct if_quotactl&quot; &quot; *qctl)
 609
 610 struct if_quotactl {
 611         __u32                   qc_cmd;
 612         __u32                   qc_type;
 613         __u32                   qc_id;
 614         __u32                   qc_stat;
 615         struct obd_dqinfo       qc_dqinfo;
 616         struct obd_dqblk        qc_dqblk;
 617         char                    obd_type[16];
 618         struct obd_uuid         obd_uuid;
 619 };
 620 struct obd_dqblk {
 621         __u64 dqb_bhardlimit;
 622         __u64 dqb_bsoftlimit;
 623         __u64 dqb_curspace;
 624         __u64 dqb_ihardlimit;
 625         __u64 dqb_isoftlimit;
 626         __u64 dqb_curinodes;
 627         __u64 dqb_btime;
 628         __u64 dqb_itime;
 629         __u32 dqb_valid;
 630         __u32 padding;
 631 };
 632 struct obd_dqinfo {
 633         __u64 dqi_bgrace;
 634         __u64 dqi_igrace;
 635         __u32 dqi_flags;
 636         __u32 dqi_valid;
 637 };
 638 struct obd_uuid {
 639         char uuid[40];
 640 };</screen>
 641     </section>
 642     <section remap="h5">
 643       <title>Description</title>
 644       <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>
 645       <informaltable frame="all">
 646         <tgroup cols="2">
 647           <colspec colname="c1" colwidth="50*"/>
 648           <colspec colname="c2" colwidth="50*"/>
 649           <thead>
 650             <row>
 651               <entry>
 652                 <para><emphasis role="bold">Option</emphasis></para>
 653               </entry>
 654               <entry>
 655                 <para><emphasis role="bold">Description</emphasis></para>
 656               </entry>
 657             </row>
 658           </thead>
 659           <tbody>
 660             <row>
 661               <entry>
 662                 <para> <literal>LUSTRE_Q_QUOTAON</literal></para>
 663               </entry>
 664               <entry>
 665                 <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>
 666               </entry>
 667             </row>
 668             <row>
 669               <entry>
 670                 <para> <literal>LUSTRE_Q_QUOTAOFF</literal></para>
 671               </entry>
 672               <entry>
 673                 <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>
 674               </entry>
 675             </row>
 676             <row>
 677               <entry>
 678                 <para> <literal>LUSTRE_Q_GETQUOTA</literal></para>
 679               </entry>
 680               <entry>
 681                 <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>
 682               </entry>
 683             </row>
 684             <row>
 685               <entry>
 686                 <para> <literal>LUSTRE_Q_SETQUOTA</literal></para>
 687               </entry>
 688               <entry>
 689                 <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>
 690               </entry>
 691             </row>
 692             <row>
 693               <entry>
 694                 <para> <literal>LUSTRE_Q_GETINFO</literal></para>
 695               </entry>
 696               <entry>
 697                 <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>
 698               </entry>
 699             </row>
 700             <row>
 701               <entry>
 702                 <para> <literal>LUSTRE_Q_SETINFO</literal></para>
 703               </entry>
 704               <entry>
 705                 <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>
 706               </entry>
 707             </row>
 708           </tbody>
 709         </tgroup>
 710       </informaltable>
 711     </section>
 712     <section remap="h5">
 713       <title>Return Values</title>
 714       <para><literal>llapi_quotactl()</literal> returns:</para>
 715       <para><literal>0</literal> On success</para>
 716       <para><literal> -1 </literal> On failure and sets error number (<literal>errno</literal>) to indicate the error</para>
 717     </section>
 718     <section remap="h5">
 719       <title>Errors</title>
 720       <para><literal>llapi_quotactl</literal> errors are described below.</para>
 721       <informaltable frame="all">
 722         <tgroup cols="2">
 723           <colspec colname="c1" colwidth="50*"/>
 724           <colspec colname="c2" colwidth="50*"/>
 725           <thead>
 726             <row>
 727               <entry>
 728                 <para><emphasis role="bold">Errors</emphasis></para>
 729               </entry>
 730               <entry>
 731                 <para><emphasis role="bold">Description</emphasis></para>
 732               </entry>
 733             </row>
 734           </thead>
 735           <tbody>
 736             <row>
 737               <entry>
 738                 <para> <literal>EFAULT</literal></para>
 739               </entry>
 740               <entry>
 741                 <para><emphasis>qctl</emphasis> is invalid.</para>
 742               </entry>
 743             </row>
 744             <row>
 745               <entry>
 746                 <para> <literal>ENOSYS</literal></para>
 747               </entry>
 748               <entry>
 749                 <para>Kernel or Lustre modules have not been compiled with the <literal>QUOTA</literal> option.</para>
 750               </entry>
 751             </row>
 752             <row>
 753               <entry>
 754                 <para> <literal>ENOMEM</literal></para>
 755               </entry>
 756               <entry>
 757                 <para>Insufficient memory to complete operation.</para>
 758               </entry>
 759             </row>
 760             <row>
 761               <entry>
 762                 <para> <literal>ENOTTY</literal></para>
 763               </entry>
 764               <entry>
 765                 <para> <emphasis>qc_cmd</emphasis> is invalid.</para>
 766               </entry>
 767             </row>
 768             <row>
 769               <entry>
 770                 <para> <literal>EBUSY</literal></para>
 771               </entry>
 772               <entry>
 773                 <para>Cannot process during quotacheck.</para>
 774               </entry>
 775             </row>
 776             <row>
 777               <entry>
 778                 <para> <literal>ENOENT</literal></para>
 779               </entry>
 780               <entry>
 781                 <para> <emphasis>uuid</emphasis> does not correspond to OBD or <emphasis>mnt</emphasis> does not exist.</para>
 782               </entry>
 783             </row>
 784             <row>
 785               <entry>
 786                 <para> <literal>EPERM</literal></para>
 787               </entry>
 788               <entry>
 789                 <para>The call is privileged and the caller is not the super user.</para>
 790               </entry>
 791             </row>
 792             <row>
 793               <entry>
 794                 <para> <literal>ESRCH</literal></para>
 795               </entry>
 796               <entry>
 797                 <para>No disk quota is found for the indicated user. Quotas have not been turned on for this file system.</para>
 798               </entry>
 799             </row>
 800           </tbody>
 801         </tgroup>
 802       </informaltable>
 803     </section>
 804   </section>
 805   <section xml:id="dbdoclet.50438215_15718">
 806     <title>
 807       <literal>llapi_path2fid</literal>
 808     </title>
 809     <para>Use <literal>llapi_path2fid</literal> to get the FID from the pathname.</para>
 810     <section remap="h5">
 811       <title>Synopsis</title>
 812       <screen>#include &lt;lustre/liblustreapi.h&gt;
 813 #include &lt;lustre/lustre_user.h&gt;
 814
 815 int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid, unsigned long *ver)</screen>
 816     </section>
 817     <section remap="h5">
 818       <title>Description</title>
 819       <para>The <literal>llapi_path2fid</literal> function returns the FID (sequence : object ID : version) for the pathname.</para>
 820     </section>
 821     <section remap="h5">
 822       <title>Return Values</title>
 823       <para><literal>llapi_path2fid</literal> returns:</para>
 824       <para><literal>0</literal> On success</para>
 825       <para>non-zero value On failure</para>
 826     </section>
 827   </section>
 828   <section xml:id="dbdoclet.50438215_marker-1297700">
 829     <title>Example Using the <literal>llapi</literal> Library</title>
 830     <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>
 831     <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>
 832     <para><emphasis role="bold">A simple C program to demonstrate striping API - libtest.c</emphasis></para>
 833     <screen>/* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
 834  * vim:expandtab:shiftwidth=8:tabstop=8:
 835  *
 836  * lustredemo - simple code examples of liblustreapi functions
 837  */
 838
 839 #include &lt;stdio.h&gt;
 840 #include &lt;fcntl.h&gt;
 841 #include &lt;sys/stat.h&gt;
 842 #include &lt;sys/types.h&gt;
 843 #include &lt;dirent.h&gt;
 844 #include &lt;errno.h&gt;
 845 #include &lt;string.h&gt;
 846 #include &lt;unistd.h&gt;
 847 #include &lt;stdlib.h&gt;
 848 #include &lt;lustre/liblustreapi.h&gt;
 849 #include &lt;lustre/lustre_user.h&gt;
 850 #define MAX_OSTS 1024
 851 #define LOV_EA_SIZE(lum, num) (sizeof(*lum) + num * sizeof(*lum-&gt;lmm_objects))
 852 #define LOV_EA_MAX(lum) LOV_EA_SIZE(lum, MAX_OSTS)
 853
 854
 855
 856
 857
 858 /*
 859 This program provides crude examples of using the liblustre API functions
 860 */
 861
 862 /* Change these definitions to suit */
 863
 864
 865
 866
 867 #define TESTDIR &quot;/tmp&quot;           /* Results directory */
 868 #define TESTFILE &quot;lustre_dummy&quot;  /* Name for the file we create/destroy */
 869 #define FILESIZE 262144                    /* Size of the file in words */
 870 #define DUMWORD &quot;DEADBEEF&quot;       /* Dummy word used to fill files */
 871 #define MY_STRIPE_WIDTH 2                  /* Set this to the number of OST required */
 872 #define MY_LUSTRE_DIR &quot;/mnt/lustre/ftest&quot;
 873
 874
 875 int close_file(int fd)
 876 {
 877    if (close(fd) &lt; 0) {
 878            fprintf(stderr, &quot;File close failed: %d (%s)\n&quot;, errno, strerror(errno));
 879            return -1;
 880    }
 881    return 0;
 882 }
 883
 884 int write_file(int fd)
 885 {
 886    char *stng =  DUMWORD;
 887    int cnt = 0;
 888
 889    for( cnt = 0; cnt &lt; FILESIZE; cnt++) {
 890                 write(fd, stng, sizeof(stng));
 891    }
 892    return 0;
 893 }
 894 /* Open a file, set a specific stripe count, size and starting OST
 895    Adjust the parameters to suit */
 896
 897 int open_stripe_file()
 898 {
 899    char *tfile = TESTFILE;
 900    int stripe_size = 65536;    /* System default is 4M */
 901    int stripe_offset = -1;     /* Start at default */
 902    int stripe_count = MY_STRIPE_WIDTH;  /*Single stripe for this demo*/
 903    int stripe_pattern = 0;     /* only RAID 0 at this time */
 904    int rc, fd;
 905    /*
 906    */
 907    rc = llapi_file_create(tfile,
 908 stripe_size,stripe_offset,stripe_count,stripe_pattern);
 909    /* result code is inverted, we may return -EINVAL or an ioctl error.
 910    We borrow an error message from sanity.c
 911    */
 912    if (rc) {
 913                 fprintf(stderr,&quot;llapi_file_create failed: %d (%s) \n&quot;, rc, strerror(-rc));
 914                 return -1;
 915         }
 916         /* llapi_file_create closes the file descriptor, we must re-open */
 917         fd = open(tfile, O_CREAT | O_RDWR | O_LOV_DELAY_CREATE, 0644);
 918         if (fd &lt; 0) {
 919                 fprintf(stderr, &quot;Can&apos;t open %s file: %d (%s)\n&quot;, tfile, errno, strerror(errno));
 920            return -1;
 921         }
 922         return fd;
 923 }
 924
 925 /* output a list of uuids for this file */
 926 int get_my_uuids(int fd)
 927 {
 928    struct obd_uuid uuids[1024], *uuidp;        /* Output var */
 929    int obdcount = 1024;
 930    int rc,i;
 931
 932    rc = llapi_lov_get_uuids(fd, uuids, &amp;obdcount);
 933    if (rc != 0) {
 934            fprintf(stderr, &quot;get uuids failed: %d (%s)\n&quot;,errno, strerror(errno));
 935         }
 936         printf(&quot;This file system has %d obds\n&quot;, obdcount);
 937         for (i = 0, uuidp = uuids; i &lt; obdcount; i++, uuidp++) {
 938            printf(&quot;UUID %d is %s\n&quot;,i, uuidp-&gt;uuid);
 939         }
 940         return 0;
 941 }
 942
 943 /* Print out some LOV attributes. List our objects */
 944 int get_file_info(char *path)
 945 {
 946
 947    struct lov_user_md *lump;
 948    int rc;
 949    int i;
 950
 951    lump = malloc(LOV_EA_MAX(lump));
 952    if (lump == NULL) {
 953            return -1;
 954         }
 955
 956         rc = llapi_file_get_stripe(path, lump);
 957
 958         if (rc != 0) {
 959            fprintf(stderr, &quot;get_stripe failed: %d (%s)\n&quot;,errno, strerror(errno));
 960            return -1;
 961         }
 962
 963    printf(&quot;Lov magic %u\n&quot;, lump-&gt;lmm_magic);
 964    printf(&quot;Lov pattern %u\n&quot;, lump-&gt;lmm_pattern);
 965    printf(&quot;Lov object id %llu\n&quot;, lump-&gt;lmm_object_id);
 966    printf(&quot;Lov object group %llu\n&quot;, lump-&gt;lmm_object_gr);
 967    printf(&quot;Lov stripe size %u\n&quot;, lump-&gt;lmm_stripe_size);
 968    printf(&quot;Lov stripe count %hu\n&quot;, lump-&gt;lmm_stripe_count);
 969    printf(&quot;Lov stripe offset %u\n&quot;, lump-&gt;lmm_stripe_offset);
 970    for (i = 0; i &lt; lump-&gt;lmm_stripe_count; i++) {
 971            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);
 972         }
 973
 974
 975    free(lump);
 976    return rc;
 977
 978 }
 979 /* Ping all OSTs that belong to this filesysem */
 980
 981 int ping_osts()
 982 {
 983    DIR *dir;
 984    struct dirent *d;
 985    char osc_dir[100];
 986    int rc;
 987
 988    sprintf(osc_dir, &quot;/proc/fs/lustre/osc&quot;);
 989    dir = opendir(osc_dir);
 990    if (dir == NULL) {
 991            printf(&quot;Can&apos;t open dir\n&quot;);
 992            return -1;
 993    }
 994    while((d = readdir(dir)) != NULL) {
 995            if ( d-&gt;d_type == DT_DIR ) {
 996                    if (! strncmp(d-&gt;d_name, &quot;OSC&quot;, 3)) {
 997                            printf(&quot;Pinging OSC %s &quot;, d-&gt;d_name);
 998                            rc = llapi_ping(&quot;osc&quot;, d-&gt;d_name);
 999                            if (rc) {
1000                                    printf(&quot;  bad\n&quot;);
1001                            } else {
1002                                    printf(&quot;  good\n&quot;);
1003                            }
1004                    }
1005            }
1006    }
1007    return 0;
1008
1009 }
1010
1011 int main()
1012 {
1013    int file;
1014    int rc;
1015    char filename[100];
1016    char sys_cmd[100];
1017
1018    sprintf(filename, &quot;%s/%s&quot;,MY_LUSTRE_DIR, TESTFILE);
1019
1020    printf(&quot;Open a file with striping\n&quot;);
1021    file = open_stripe_file();
1022    if ( file &lt; 0 ) {
1023            printf(&quot;Exiting\n&quot;);
1024            exit(1);
1025
1026
1027
1028
1029    }
1030    printf(&quot;Getting uuid list\n&quot;);
1031    rc = get_my_uuids(file);
1032    rintf(&quot;Write to the file\n&quot;);
1033    rc = write_file(file);
1034    rc = close_file(file);
1035    printf(&quot;Listing LOV data\n&quot;);
1036    rc = get_file_info(filename);
1037    printf(&quot;Ping our OSTs\n&quot;);
1038    rc = ping_osts();
1039
1040    /* the results should match lfs getstripe */
1041    printf(&quot;Confirming our results with lfs getsrtipe\n&quot;);
1042    sprintf(sys_cmd, &quot;/usr/bin/lfs getstripe %s/%s&quot;, MY_LUSTRE_DIR, TESTFILE);
1043    system(sys_cmd);
1044
1045    printf(&quot;All done\n&quot;);
1046    exit(rc);
1047 }
1048 </screen>
1049     <para><emphasis role="bold">Makefile for sample application:</emphasis></para>
1050     <screen>
1051 gcc -g -O2 -Wall -o lustredemo libtest.c -llustreapi
1052 clean:
1053 rm -f core lustredemo *.o
1054 run:
1055 make
1056 rm -f /mnt/lustre/ftest/lustredemo
1057 rm -f /mnt/lustre/ftest/lustre_dummy
1058 cp lustredemo /mnt/lustre/ftest/
1059 </screen>
1060     <section remap="h5">
1061       <title>See Also</title>
1062       <itemizedlist>
1063         <listitem>
1064           <para>
1065             <xref linkend="dbdoclet.50438215_30970"/>
1066     </para>
1067         </listitem>
1068         <listitem>
1069           <para>
1070             <xref linkend="dbdoclet.50438215_50149"/>
1071     </para>
1072         </listitem>
1073         <listitem>
1074           <para>
1075             <xref linkend="dbdoclet.50438215_86607"/>
1076     </para>
1077         </listitem>
1078         <listitem>
1079           <para>
1080             <xref linkend="dbdoclet.50438215_12433"/>
1081     </para>
1082         </listitem>
1083       </itemizedlist>
1084     </section>
1085   </section>
1086 </chapter>