lustre/doc/llapi_file_get_stripe.3

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