lustre/doc/llapi_file_get_stripe.3

   1 .TH lustreapi 3 "2009 Jul 22" The Lustre user application interface library
   2 .SH NAME
   3 llapi_file_get_stripe \- get striping information for a file or a directory on a Lustre filesystem
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <sys/types.h>
   7 .B #include <sys/stat.h>
   8 .B #include <fcntl.h>
   9 .B #include <lustre/lustreapi.h>
  10 .sp
  11 .BI "int llapi_file_get_stripe(const char *"path ", void *"lum );
  12 .sp
  13 .fi
  14 .SH DESCRIPTION
  15 .LP
  16 .B llapi_file_get_stripe(\|)
  17 returns striping information for a file or a directory
  18 .I path
  19 in
  20 .I lum
  21 (which should point to a large enough memory region) in one of the following formats:
  22
  23 .nf
  24 struct lov_user_md_v1 {
  25         __u32 lmm_magic;
  26         __u32 lmm_pattern;
  27         __u64 lmm_object_id;
  28         __u64 lmm_object_seq;
  29         __u32 lmm_stripe_size;
  30         __u16 lmm_stripe_count;
  31         __u16 lmm_stripe_offset;
  32         struct lov_user_ost_data_v1 lmm_objects[0];
  33 } __attribute__((packed));
  34
  35 struct lov_user_md_v3 {
  36         __u32 lmm_magic;
  37         __u32 lmm_pattern;
  38         __u64 lmm_object_id;
  39         __u64 lmm_object_seq;
  40         __u32 lmm_stripe_size;
  41         __u16 lmm_stripe_count;
  42         __u16 lmm_stripe_offset;
  43         char  lmm_pool_name[LOV_MAXPOOLNAME + 1];
  44         struct lov_user_ost_data_v1 lmm_objects[0];
  45 } __attribute__((packed));
  46 .fi
  47
  48 .TP 20
  49 .I lmm_magic
  50 specifies the format of the returned striping information.
  51 .BR LOV_MAGIC_V1
  52 is used for lov_user_md_v1.
  53 .BR LOV_MAGIC_V3
  54 is used for lov_user_md_v3.
  55 .TP 20
  56 .I lmm_pattern
  57 holds the striping pattern. Only
  58 .BR LOV_PATTERN_RAID0
  59 is possible in this Lustre version.
  60 .TP 20
  61 .I lmm_object_id
  62 holds the MDS object id.
  63 .TP 20
  64 .I lmm_object_gr
  65 holds the MDS object group.
  66 .TP 20
  67 .I lmm_stripe_size
  68 holds the stripe size in bytes.
  69 .TP 20
  70 .I lmm_stripe_count
  71 holds the number of OSTs the file is striped across.
  72 .TP 20
  73 .I lmm_stripe_offset
  74 holds the OST index from which the file starts.
  75 .TP 20
  76 .I lmm_pool_name
  77 holds the OST pool name to which the file belongs.
  78 .TP 20
  79 .I lmm_objects
  80 is an array of
  81 .I lmm_stripe_count
  82 members containing per OST file information in the following format:
  83
  84 .nf
  85 struct lov_user_ost_data_v1 {
  86         __u64 l_object_id;
  87         __u64 l_object_seq;
  88         __u32 l_ost_gen;
  89         __u32 l_ost_idx;
  90 } __attribute__((packed));
  91 .fi
  92 .TP 20
  93 .I l_object_id
  94 holds the OST object id.
  95 .TP 20
  96 .I l_object_seq
  97 holds the OST object group.
  98 .TP 20
  99 .I l_ost_gen
 100 holds the generation of the OST index.
 101 .TP 20
 102 .I l_ost_idx
 103 holds the OST index in LOV.
 104 .SH RETURN VALUES
 105 .LP
 106 .B llapi_file_get_stripe(\|)
 107 returns:
 108 .TP
 109 0
 110 on success
 111 .TP
 112 != 0
 113 on failure,
 114 .I errno
 115 is set appropriately.
 116 .SH ERRORS
 117 .TP 15
 118 .SM ENOMEM
 119 failed to allocate memory.
 120 .TP 15
 121 .SM ENAMETOOLONG
 122 .I path
 123 was too long.
 124 .TP 15
 125 .SM ENOENT
 126 .I path
 127 does not point to a file or a directory.
 128 .TP 15
 129 .SM ENOTTY
 130 .I path
 131 does not point to a Lustre filesystem.
 132 .TP 15
 133 .SM EFAULT
 134 memory region pointed by
 135 .I lum
 136 is not properly mapped.
 137 .SH "EXAMPLE"
 138 .nf
 139 #include <sys/vfs.h>
 140 #include <lustre/lustreapi.h>
 141
 142 static inline int maxint(int a, int b)
 143 {
 144         return a > b ? a : b;
 145 }
 146
 147 static void *alloc_lum()
 148 {
 149         int v1, v3, join;
 150
 151         v1 = sizeof(struct lov_user_md_v1) +
 152              LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
 153         v3 = sizeof(struct lov_user_md_v3) +
 154              LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
 155
 156         return malloc(maxint(v1, v3));
 157 }
 158
 159 int main(int argc, char** argv)
 160 {
 161         struct lov_user_md *lum_file = NULL;
 162         int rc;
 163         int lum_size;
 164
 165         if (argc != 2) {
 166                 fprintf(stderr, "Usage: %s <filename>\\n", argv[0]);
 167                 return 1;
 168         }
 169
 170         lum_file = alloc_lum();
 171         if (lum_file == NULL) {
 172                 rc = ENOMEM;
 173                 goto cleanup;
 174         }
 175
 176         rc = llapi_file_get_stripe(argv[1], lum_file);
 177         if (rc) {
 178                 rc = errno;
 179                 goto cleanup;
 180         }
 181
 182         /* stripe_size stripe_count */
 183         printf("%d %d\\n",
 184                lum_file->lmm_stripe_size,
 185                lum_file->lmm_stripe_count);
 186
 187 cleanup:
 188         if (lum_file != NULL)
 189                 free(lum_file);
 190
 191         return rc;
 192 }
 193 .fi
 194 .SH "SEE ALSO"
 195 .BR lustre (7),
 196 .BR lustreapi (7)