Whamcloud - gitweb
LU-5579 tests: Add test for resend enqueue vs lock destroy
[fs/lustre-release.git] / lustre / doc / llapi_layout.7
1 .TH llapi_layout 7 "2013 Oct 31" "Lustre User API"
2 .SH NAME
3 llapi_layout \- abstract interface to the layout of a Lustre file
4 .SH SYNOPSIS
5 .nf
6 .B #include <lustre/lustreapi.h>
7 .SH DESCRIPTION
8 .LP
9 The
10 .B llapi_layout
11 family of functions functions provides an abstract interface to
12 manipulating the layout information of a file in a Lustre filesystem.
13 Layouts are represented by the opaque data type
14 .B llapi_layout_t
15 which is passed as a handle to the various functions.
16 .PP
17 A layout has a number of attributes that describe how a file's data are
18 stored in the filesystem.  These include stripe count, stripe size, RAID
19 pattern, pool name, and the OST index associated with each stripe. Refer
20 to the Lustre Operations Manual for detailed descriptions of these
21 attributes.  For each attribute, there exists a pair of functions with
22 the suffixes
23 .B _get
24 and
25 .B _set
26 that are used to read and assign the attribute value in a given layout.
27 .PP
28 Using this interface to create a file might consist of the following steps.
29 .IP \[bu]
30 Allocate a layout with
31 .BR llapi_layout_alloc() .
32 .IP \[bu]
33 Assign attribute values using the
34 .B llapi_layout_*_set()
35 functions.
36 .IP \[bu]
37 Create the file using
38 .BR llapi_layout_file_create() .
39 .IP \[bu]
40 Free the layout memory using
41 .BR llapi_layout_free() .
42 .PP
43 Similarly, these steps might be used to read a file layout:
44 .IP \[bu]
45 Obtain the layout with
46 .BR llapi_layout_get_by_path() ,
47 .BR llapi_layout_get_by_fd() ,
48 or
49 .BR llapi_layout_get_by_fid() .
50 .IP \[bu]
51 Read attribute values using the
52 .B llapi_layout_*_get()
53 functions.
54 .IP \[bu]
55 Free the layout memory using
56 .BR llapi_layout_free() .
57 .SH "EXAMPLE"
58 .nf
59 #include <errno.h>
60 #include <string.h>
61 #include <stdint.h>
62 #include <unistd.h>
63 #include <stdio.h>
64 #include <lustre/lustreapi.h>
65
66 int main(int argc, char *argv[])
67 {
68         int             fd;
69         struct llapi_layout *layout;
70         uint64_t        count = 2;
71         uint64_t        size = 1048576;
72         char            *path;
73
74         if (argc != 2)
75                 return -1;
76
77         path = argv[1];
78         layout = llapi_layout_alloc();
79         llapi_layout_stripe_count_set(layout, count);
80         llapi_layout_stripe_size_set(layout, size);
81         fd = llapi_layout_file_create(path, 0, 0640, layout);
82         if (fd < 0) {
83                 fprintf(stderr, "cannot create %s: %s\\n", path,
84                         strerror(errno));
85                 return -1;
86         }
87         close(fd);
88         llapi_layout_free(layout);
89
90         layout = llapi_layout_get_by_path(path, 0);
91         llapi_layout_stripe_size_get(layout, &size),
92         llapi_layout_stripe_count_get(layout, &count);
93         printf("%s with stripe size %llu, striped across %llu OSTs,"
94                " has been created!\\n", path, size, count);
95         llapi_layout_free(layout);
96         return 0;
97 }
98 .fi
99 .SH "BUGS"
100 Setting the OST index number is only supported for stripe number 0.
101
102 The RAID pattern may only be set to 0.
103 .SH "SEE ALSO"
104 .BR open (2),
105 .BR lustre (7),
106 .BR lustreapi (7),
107 .BR llapi_layout_alloc (3),
108 .BR llapi_layout_file_create (3),
109 .BR llapi_layout_file_open (3),
110 .BR llapi_layout_free (3),
111 .BR llapi_layout_get_by_fd (3),
112 .BR llapi_layout_get_by_fid (3),
113 .BR llapi_layout_get_by_path (3),
114 .BR llapi_layout_ost_index_get (3),
115 .BR llapi_layout_ost_index_set (3),
116 .BR llapi_layout_pattern_get (3),
117 .BR llapi_layout_pattern_set (3),
118 .BR llapi_layout_pool_name_get (3),
119 .BR llapi_layout_pool_name_set (3),
120 .BR llapi_layout_stripe_count_get (3),
121 .BR llapi_layout_stripe_count_set (3),
122 .BR llapi_layout_stripe_size_get (3),
123 .BR llapi_layout_stripe_size_set (3),
124 .BR lfs (1)