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