SettingLustreProperties.xml

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