X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=SettingLustreProperties.xml;h=ce5ba82e95e0b35a992462ffbb61c201d8b50e07;hb=fa289da8d2a3a5f4f3028a2bbf0ba69ae8e91d2c;hp=d023dabe5f91958bb1d79c5ffccce99b570e4eff;hpb=c6c2d10cabf26de1363090e397a20e0ec61f85a1;p=doc%2Fmanual.git diff --git a/SettingLustreProperties.xml b/SettingLustreProperties.xml index d023dab..ce5ba82 100644 --- a/SettingLustreProperties.xml +++ b/SettingLustreProperties.xml @@ -1,5 +1,4 @@ - - + Setting Lustre Properties in a C Program (<literal>llapi</literal>) This chapter describes the llapi library of commands used for setting Lustre file properties within a C program running in a cluster environment, such as a data processing or MPI application. The commands described in this chapter are: @@ -36,7 +35,9 @@ int llapi_file_create(char *name, long stripe_size, int stripe_offset, int strip
Description - The llapi_file_create() function sets a file descriptor's Lustre striping information. The file descriptor is then accessed with open(). + The llapi_file_create() function sets a file descriptor's Lustre + file system striping information. The file descriptor is then accessed with + open(). @@ -188,7 +189,8 @@ struct lov_user_ost_data_v1 lmm_objects[0]; lmm_pattern - Holds the striping pattern. Only LOV_PATTERN_RAID0 is possible in this Lustre version. + Holds the striping pattern. Only LOV_PATTERN_RAID0 is + possible in this Lustre software release. @@ -413,7 +415,8 @@ cleanup: <literal>llapi_file_open</literal> - The llapi_file_open command opens (or creates) a file or device on a Lustre filesystem. + The llapi_file_open command opens (or creates) a file or device on a + Lustre file system.
Synopsis #include <lustre/lustreapi.h> @@ -428,7 +431,8 @@ int llapi_file_create(const char *name, unsigned long long
Description The llapi_file_create() call is equivalent to the llapi_file_open call with flags equal to O_CREAT|O_WRONLY and mode equal to 0644, followed by file close. - llapi_file_open() opens a file with a given name on a Lustre filesystem. + llapi_file_open() opens a file with a given name on a Lustre file + system. @@ -489,7 +493,9 @@ int llapi_file_create(const char *name, unsigned long long stripe_pattern - Specifies the striping pattern. In this version of Lustre, only LOV_PATTERN_RAID0 is available. The default value is 0. + Specifies the striping pattern. In this release of the Lustre software, only + LOV_PATTERN_RAID0 is available. The default value is + 0. @@ -548,7 +554,8 @@ int llapi_file_create(const char *name, unsigned long long ENOTTY - name may not point to a Lustre filesystem. + + name may not point to a Lustre file system. @@ -643,7 +650,14 @@ struct obd_uuid { LUSTRE_Q_QUOTAON - Turns on quotas for a Lustre file system. Deprecated as of 2.4.0. qc_type is USRQUOTA, GRPQUOTA or UGQUOTA (both user and group quota). The quota files must exist. They are normally created with the llapi_quotacheck call. This call is restricted to the super user privilege. As of 2.4.0, quota is now enabled on a per-filesystem basis via lctl conf_param (see ) on the MGS node and quotacheck isn't needed any more. + Turns on quotas for a Lustre file system. Deprecated as of 2.4.0. + qc_type is USRQUOTA, + GRPQUOTA or UGQUOTA (both user and group + quota). The quota files must exist. They are normally created with the + llapi_quotacheck call. This call is restricted to the super + user privilege. As of 2.4.0, quota is now enabled on a per file system basis via + lctl conf_param (see ) + on the MGS node and quotacheck isn't needed any more. @@ -675,7 +689,12 @@ struct obd_uuid { LUSTRE_Q_GETINFO - Gets information about quotas. qc_type is either USRQUOTA or GRPQUOTA. On return, dqi_igrace is inode grace time (in seconds), dqi_bgrace is block grace time (in seconds), dqi_flags is not used by the current Lustre version. + Gets information about quotas. qc_type is either + USRQUOTA or GRPQUOTA. On return, + dqi_igrace is inode grace time (in seconds), + dqi_bgrace is block grace time (in seconds), + dqi_flags is not used by the current release of the Lustre + software. @@ -683,7 +702,12 @@ struct obd_uuid { LUSTRE_Q_SETINFO - Sets quota information (like grace times). qc_type is either USRQUOTA or GRPQUOTA. dqi_igrace is inode grace time (in seconds), dqi_bgrace is block grace time (in seconds), dqi_flags is not used by the current Lustre version and must be zeroed. + Sets quota information (like grace times). qc_type is + either USRQUOTA or GRPQUOTA. + dqi_igrace is inode grace time (in seconds), + dqi_bgrace is block grace time (in seconds), + dqi_flags is not used by the current release of the Lustre + software and must be zeroed. @@ -805,9 +829,205 @@ int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid non-zero value On failure
+
+ + <literal>llapi_ladvise</literal> + + Use llapi_ladvise to give IO advice/hints on a + Lustre file to the server. +
+ Synopsis + +#include <lustre/lustreapi.h> +int llapi_ladvise(int fd, unsigned long long flags, + int num_advise, struct llapi_lu_ladvise *ladvise); + +struct llapi_lu_ladvise { + __u16 lla_advice; /* advice type */ + __u16 lla_value1; /* values for different advice types */ + __u32 lla_value2; + __u64 lla_start; /* first byte of extent for advice */ + __u64 lla_end; /* last byte of extent for advice */ + __u32 lla_value3; + __u32 lla_value4; +}; + +
+
+ Description + The llapi_ladvise function passes an array of + num_advise I/O hints (up to a maximum of + LAH_COUNT_MAX items) in ladvise for the file + descriptor fd from an application to one or more + Lustre servers. Optionally, flags can modify how + the advice will be processed via bitwise-or'd values: + + LF_ASYNC: Clients return to userspace + immediately after submitting ladvise RPCs, leaving server threads to + handle the advices asynchronously. + + Each of the ladvise elements is an + llapi_lu_ladvise structure, which contains the + following fields: + + + + + + + + Field + + + Description + + + + + + + lla_ladvice + + + Specifies the advice for the given file range, currently + one of: + LU_LADVISE_WILLREAD: Prefetch data + into server cache using optimum I/O size for the server. + LU_LADVISE_DONTNEED: Clean cached data + for the specified file range(s) on the server. + + + + + lla_start + + + The offset in bytes for the start of this advice. + + + + + lla_end + + + The offset in bytes (non-inclusive) for the end of this + advice. + + + + + lla_value1 + lla_value2 + lla_value3 + lla_value4 + + + Additional arguments for future advice types and + should be set to zero if not explicitly required for a given + advice type. + + + + + + + llapi_ladvise() forwards the advice to Lustre + servers without guaranteeing how and when servers will react to the + advice. Actions may or may not be triggered when the advices are + received, depending on the type of the advice as well as the real-time + decision of the affected server-side components. + + A typical usage of llapi_ladvise() is to + enable applications and users (via lfs ladvise) + with external knowledge about application I/O patterns to intervene in + server-side I/O handling. For example, if a group of different clients + are doing small random reads of a file, prefetching pages into OSS + cache with big linear reads before the random IO is an overall net + benefit. Fetching that data into each client cache with + fadvise() may not be beneficial, due to much more + data being sent to the clients. + + While conceptually similar to the + posix_fadvise and Linux + fadvise system calls, the main difference of + llapi_ladvise() is that + fadvise() / posix_fadvise() are client side + mechanisms that do not pass advice to the filesystem, while + llapi_ladvise() sends advice or hints to one or + more Lustre servers on which the file is stored. In some cases it may + be desirable to use both interfaces. + +
+
+ Return Values + llapi_ladvise returns: + 0 On success + -1 if an error occurred (in which case, errno + is set appropriately). +
+
+ Errors + + + + + + + + + Error + + + Description + + + + + + + ENOMEM + + + Insufficient memory to complete operation. + + + + + EINVAL + + + One or more invalid arguments are given. + + + + + EFAULT + + + Memory region pointed by + ladvise is not properly mapped. + + + + + + ENOTSUPP + + + Advice type is not supported. + + + + + + +
+
Example Using the <literal>llapi</literal> Library - Use llapi_file_create to set Lustre properties for a new file. For a synopsis and description of llapi_file_create and examples of how to use it, see . + Use llapi_file_create to set Lustre software properties for a new file. + For a synopsis and description of llapi_file_create and examples of how to + use it, see . You can set striping from inside programs like ioctl. To compile the sample program, you need to install the Lustre client source RPM. A simple C program to demonstrate striping API - libtest.c