lustre/doc/llapi_fid_parse.3

   1 .TH lustreapi 3 "2019 Sep 13" Lustre user application interface library
   2 .SH NAME
   3 llapi_fid_parse \- parse ASCII FID string into binary lu_fid
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .sp
   8 .BI "int llapi_fid_parse(const char *" fidstr ", struct lu_fid *" fid ,
   9 .BI "                    char **" endptr ");"
  10 .sp
  11 .fi
  12 .SH DESCRIPTION
  13 .LP
  14 .B llapi_fid_parse()
  15 converts an ASCII FID string into a binary
  16 .B struct lu_fid
  17 for use in other interfaces such as
  18 .BR llapi_layout_get_by_fid() .
  19 .I fidstr
  20 should contain three numbers in the form
  21 .IR fid_seq : fid_oid : fid_ver
  22 and may optionally be enclosed in square braces
  23 .BR [] .
  24 It will skip any leading whitespace before the FID.
  25 .LP
  26 If
  27 .I endptr
  28 is not NULL,
  29 .B llapi_fid_parse()
  30 stores the address of the first invalid character in
  31 .IR *endptr ,
  32 or the character immediately following the end of the parsed FID.
  33 .SH RETURN VALUES
  34 .LP
  35 .B llapi_fid_parse()
  36 returns:
  37 .TP
  38 0
  39 on success,
  40 .TP
  41 <0
  42 a negative errno on failure and sets errno.
  43 .SH ERRORS
  44 .TP 15
  45 .SM EINVAL
  46 .I fidstr
  47 is NULL or does not contain a valid FID format.
  48 .TP
  49 .SM ERANGE
  50 .I fidstr
  51 contains numeric values that exceed valid values for a component.
  52 .SH "EXAMPLE"
  53 .nf
  54 #include <lustre/lustreapi.h>
  55
  56 int main(int argc, char *argv[])
  57 {
  58         char fidstr = "[0x200000004:0x2:0x0] [0x200000400:0x345:0x0]";
  59         struct lu_fid fid1, fid2;
  60         char *end;
  61         int rc;
  62
  63         fidstr = argv[1];
  64         rc = llapi_fid_parse(fidstr, &fid1, &end);
  65         if (rc < 0) {
  66                 fprintf(stderr, "invalid first FID '%s': %s\\n",
  67                         fidstr, strerror(-rc));
  68                 return -1;
  69         }
  70
  71         fidstr = end;
  72         rc = llapi_fid_parse(fidstr, &fid2, &end);
  73         if (rc < 0) {
  74                 fprintf(stderr, "invalid second FID '%s': %s\\n",
  75                         fidstr, strerror(-rc));
  76                 return -1;
  77         }
  78
  79         printf("fid1=" DFID " fid2="DFID"\\n", PFID(&fid1), PFID(&fid2));
  80         return 0;
  81 }
  82 .fi
  83 .SH "SEE ALSO"
  84 .BR lustre (7),
  85 .BR llapi_path2parent (3),
  86 .BR lustreapi (7)