From 7b9b258b5eeaeb3191b7fb302c55ef1cd678ba64 Mon Sep 17 00:00:00 2001 From: panda Date: Tue, 15 Sep 2009 14:15:39 +0000 Subject: [PATCH] b=16267 i=Johann Lombardi i=Vitaly Fertman llapi man pages --- lustre/doc/Makefile.am | 3 +- lustre/doc/liblustreapi.7 | 11 ++ lustre/doc/llapi_file_create.3 | 1 + lustre/doc/llapi_file_get_stripe.3 | 222 +++++++++++++++++++++++++++++++++++++ lustre/doc/llapi_file_open.3 | 3 +- lustre/doc/llapi_quotactl.3 | 3 +- lustre/doc/lustre.7 | 3 +- 7 files changed, 242 insertions(+), 4 deletions(-) create mode 100644 lustre/doc/liblustreapi.7 create mode 100644 lustre/doc/llapi_file_create.3 create mode 100644 lustre/doc/llapi_file_get_stripe.3 diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index d4d36b6..84c0b52 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -49,7 +49,8 @@ SUFFIXES = .lin .lyx .pdf .ps .sgml .html .txt .tex .fig .eps .dvi MANFILES = lustre.7 lfs.1 mount.lustre.8 mkfs.lustre.8 tunefs.lustre.8 lctl.8 \ llverdev.8 llbackup.8 llapi_quotactl.3 llobdstat.8 llstat.8 \ plot-llstat.8 l_getgroups.8 lst.8 routerstat.8 lshowmount.8 \ - ll_recover_lost_found_objs.8 llog_reader.8 llapi_file_open.3 + ll_recover_lost_found_objs.8 llog_reader.8 llapi_file_open.3 \ + llapi_file_create.3 llapi_file_get_stripe.3 liblustreapi.7 if UTILS man_MANS = $(MANFILES) endif diff --git a/lustre/doc/liblustreapi.7 b/lustre/doc/liblustreapi.7 new file mode 100644 index 0000000..ebd86bf --- /dev/null +++ b/lustre/doc/liblustreapi.7 @@ -0,0 +1,11 @@ +.TH liblustreapi 7 "2009 Aug 10" Lustre liblustreapi +.SH NAME +liblustre \- The liblustre library +.SH DESCRIPTION +The liblustre library provides functions to access and/or modify settings specific to the Lustre filesystem (allocation policies, quotas, etc). +.SH "SEE ALSO" +.BR lustre (7), +.BR llapi_file_create (3), +.BR llapi_file_open (3), +.BR llapi_file_get_stripe (3), +.BR llapi_quotactl (3) diff --git a/lustre/doc/llapi_file_create.3 b/lustre/doc/llapi_file_create.3 new file mode 100644 index 0000000..60dd263 --- /dev/null +++ b/lustre/doc/llapi_file_create.3 @@ -0,0 +1 @@ +.so man3/llapi_file_open.3 diff --git a/lustre/doc/llapi_file_get_stripe.3 b/lustre/doc/llapi_file_get_stripe.3 new file mode 100644 index 0000000..e456468 --- /dev/null +++ b/lustre/doc/llapi_file_get_stripe.3 @@ -0,0 +1,222 @@ +.TH llapi_file_get_stripe 3 "2009 Jul 22" Lustre liblustreapi +.SH NAME +llapi_file_get_stripe \- get striping information for a file or a directory on a Lustre filesystem +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "int llapi_file_get_stripe(const char *"path ", void *"lum ); +.sp +.fi +.SH DESCRIPTION +.LP +.B llapi_file_get_stripe(\|) +returns striping information for a file or a directory +.I path +in +.I lum +(which should point to a large enough memory region) in one of the following formats: + +.nf +struct lov_user_md_v1 { + __u32 lmm_magic; + __u32 lmm_pattern; + __u64 lmm_object_id; + __u64 lmm_object_gr; + __u32 lmm_stripe_size; + __u16 lmm_stripe_count; + __u16 lmm_stripe_offset; + struct lov_user_ost_data_v1 lmm_objects[0]; +} __attribute__((packed)); + +struct lov_user_md_v3 { + __u32 lmm_magic; + __u32 lmm_pattern; + __u64 lmm_object_id; + __u64 lmm_object_gr; + __u32 lmm_stripe_size; + __u16 lmm_stripe_count; + __u16 lmm_stripe_offset; + char lmm_pool_name[LOV_MAXPOOLNAME]; + struct lov_user_ost_data_v1 lmm_objects[0]; +} __attribute__((packed)); + +struct lov_user_md_join { + __u32 lmm_magic; + __u32 lmm_pattern; + __u64 lmm_object_id; + __u64 lmm_object_gr; + __u32 lmm_stripe_size; + __u32 lmm_stripe_count; + __u32 lmm_extent_count; + __u64 lmm_tree_id; + __u64 lmm_tree_gen; + struct llog_logid lmm_array_id; + struct lov_user_ost_data_join lmm_objects[0]; +} __attribute__((packed)); +.fi + +.TP 20 +.I lmm_magic +specifies the format of the returned striping information. +.BR LOV_MAGIC_V1 +is used for lov_user_md_v1. +.BR LOV_MAGIC_V3 +is used for lov_user_md_v3. +.BR LOV_MAGIC_JOIN +is used for lov_user_md_join. +.TP 20 +.I lmm_pattern +holds the striping pattern. Only +.BR LOV_PATTERN_RAID0 +is possible in this Lustre version. +.TP 20 +.I lmm_object_id +holds the MDS object id. +.TP 20 +.I lmm_object_gr +holds the MDS object group. +.TP 20 +.I lmm_stripe_size +holds the stripe size in bytes. +.TP 20 +.I lmm_stripe_count +holds the number of OSTs the file is striped across. +.TP 20 +.I lmm_stripe_offset +holds the OST index from which the file starts. +.TP 20 +.I lmm_pool_name +holds the OST pool name to which the file belongs. +.TP 20 +.I lmm_objects +is an array of +.I lmm_stripe_count +members containing per OST file information in the following format: + +.nf +struct lov_user_ost_data_v1 { + __u64 l_object_id; + __u64 l_object_gr; + __u32 l_ost_gen; + __u32 l_ost_idx; +} __attribute__((packed)); +.fi +.TP 20 +.I l_object_id +holds the OST object id. +.TP 20 +.I l_object_gr +holds the OST object group. +.TP 20 +.I l_ost_gen +holds the generation of the OST index. +.TP 20 +.I l_ost_idx +holds the OST index in LOV. +.SH RETURN VALUES +.LP +.B llapi_file_get_stripe(\|) +returns: +.TP +0 +on success +.TP +!= 0 +on failure, +.I errno +is set appropriately. +.SH ERRORS +.TP 15 +.SM ENOMEM +failed to allocate memory. +.TP 15 +.SM ENAMETOOLONG +.I path +was too long. +.TP 15 +.SM ENOENT +.I path +does not point to a file or a directory. +.TP 15 +.SM ENOTTY +.I path +does not point to a Lustre filesystem. +.TP 15 +.SM EFAULT +memory region pointed by +.I lum +is not properly mapped. +.SH "EXAMPLE" +.nf +#include +#include +#include +#include +#include +#include +#include + +static inline int maxint(int a, int b) +{ + return a > b ? a : b; +} + +static void *alloc_lum() +{ + int v1, v3, join; + + v1 = sizeof(struct lov_user_md_v1) + + LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1); + v3 = sizeof(struct lov_user_md_v3) + + LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1); + join = sizeof(struct lov_user_md_join) + + LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_join); + + return malloc(maxint(maxint(v1, v3), join)); +} + +int main(int argc, char** argv) +{ + struct lov_user_md *lum_file = NULL; + int rc; + int lum_size; + + if (argc != 2) { + fprintf(stderr, "Usage: %s \\n", argv[0]); + return 1; + } + + lum_file = alloc_lum(); + if (lum_file == NULL) { + rc = ENOMEM; + goto cleanup; + } + + rc = llapi_file_get_stripe(argv[1], lum_file); + if (rc) { + rc = errno; + goto cleanup; + } + + /* stripe_size stripe_count */ + printf("%d %d\\n", + lum_file->lmm_stripe_size, + lum_file->lmm_stripe_count); + +cleanup: + if (lum_file != NULL) + free(lum_file); + + return rc; +} +.fi +.SH "SEE ALSO" +.BR lustre (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_file_open.3 b/lustre/doc/llapi_file_open.3 index 0d84d72..ce015ac 100644 --- a/lustre/doc/llapi_file_open.3 +++ b/lustre/doc/llapi_file_open.3 @@ -151,4 +151,5 @@ int main(int argc, char *argv[]) .fi .SH "SEE ALSO" .BR open (2), -.BR lustre (7) +.BR lustre (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_quotactl.3 b/lustre/doc/llapi_quotactl.3 index 87ad80c..4866c72 100644 --- a/lustre/doc/llapi_quotactl.3 +++ b/lustre/doc/llapi_quotactl.3 @@ -176,4 +176,5 @@ No disc quota is found for the indicated user. Quotas have not been turned on for this filesystem. .SH "SEE ALSO" .BR lfs (1), -.BR lustre (7) +.BR lustre (7), +.BR liblustreapi (7) diff --git a/lustre/doc/lustre.7 b/lustre/doc/lustre.7 index efa92bd..650dc97 100644 --- a/lustre/doc/lustre.7 +++ b/lustre/doc/lustre.7 @@ -70,4 +70,5 @@ http://downloads.lustre.org/ .BR tunefs.lustre (8), .BR mount.lustre (8), .BR lctl (8), -.BR lfs (1) +.BR lfs (1), +.BR liblustreapi (7) -- 1.8.3.1