LU-4315 doc: split lctl get_param and set_param man pages

[fs/lustre-release.git] / lustre / doc / llapi_ladvise.3

diff --git a/lustre/doc/llapi_ladvise.3 b/lustre/doc/llapi_ladvise.3
index fc49ef5..d755899 100644 (file)
--- a/lustre/doc/llapi_ladvise.3
+++ b/lustre/doc/llapi_ladvise.3
@@ -6,7 +6,8 @@ llapi_ladvise \- give IO advice/hints on a Lustre file to the server
 .B #include <lustre/lustreapi.h>
 .sp
 .BI "int llapi_ladvise(int " fd ", unsigned long long " flags ,
-.BI "                  int " num_advise ", struct llapi_ladvise *" ladvise ");"
+.BI "                  int " num_advise ",
+.BI "                  struct llapi_lu_ladvise *" ladvise ");"
 .sp
 .fi
 .SH DESCRIPTION
@@ -20,13 +21,16 @@ items) in
 .I ladvise
 for the file descriptor
 .I fd
-from to an application to one or more Lustre servers.  Optionally,
+from an application to one or more Lustre servers.  Optionally,
 .I flags
 can modify how the advice will be processed via bitwise-or'd values:
 .TP
 .B LF_ASYNC
-Client return to userspace immediately after submitting ladvise RPCs, leaving
+Client returns to userspace immediately after submitting ladvise RPCs, leaving
 server threads to handle the advices asynchronously.
+.TP
+.B LF_UNSET
+Unset/clear a previous advice (Currently only supports LU_ADVISE_LOCKNOEXPAND).
 .PP
 Each of the
 .I ladvise
@@ -57,6 +61,12 @@ Prefetch data into server cache using optimum I/O size for the server.
 .B LU_LADVISE_DONTNEED
 Clean cached data for the specified file range(s) on the server.
 .TP
+.B LU_LADVISE_LOCKAHEAD
+Request an LDLM extent lock of the given mode on the given byte range.
+.TP
+.B LU_LADVISE_NOEXPAND
+Disable extent lock expansion behavior for I/O to this file descriptor.
+.TP
 .I lla_start
 is the offset in bytes for the start of this advice.
 .TP
@@ -66,14 +76,31 @@ is the offset in bytes (non-inclusive) for the end of this advice.
 .IR 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.
+Advice-specific names for these fields follow.
+.TP
+.IR lla_lockahead_mode
+When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field is used to
+communicate the requested lock mode, and can be referred to as
+lla_lockahead_mode.
+.TP
+.IR lla_peradvice_flags
+When using advices which support them, the 'lla_value2' field is
+used to communicate per-advice flags and can be referred to as
+lla_peradvice_flags.  Both LF_ASYNC and LF_UNSET are supported
+as peradvice flags.
+.TP
+.IR lla_lockahead_result
+When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field is used to
+communicate the result of the request, and can be referred to as lla_lockahead_result.
+.PP
 .PP
 .B llapi_ladvise()
 forwards the advice to Lustre servers without guaranteeing how and when
-servers will react to the advice. Actions may or may not triggered when the
+servers will react to the advice. Actions may or may not be triggered when the
 advices are recieved, depending on the type of the advice as well as the
 real-time decision of the affected server-side components.
 
-A typical usage of
+Typical usage of
 .B llapi_ladvise()
 is to enable applications and users (via
 .BR "lfs ladvise" (1))
@@ -85,6 +112,13 @@ that data into each client cache with
 .B fadvise()
 may not be, due to much more data being sent to the clients.
 
+LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible and
+encouraged to use it directly in your application to avoid lock contention
+(primarily for writing to a single file from multiple clients), it will
+also be available in the MPI-I/O / MPICH library from ANL for use with the
+i/o aggregation mode of that library. This is intended (eventually) to be
+the primary way this feature is used.
+
 While conceptually similar to the
 .BR posix_fadvise (2)
 and Linux
@@ -96,7 +130,7 @@ is that
 are client side mechanisms that do not pass advice to the filesystem, while
 .B 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.
+is stored. In some cases it may be desirable to use both interfaces.
 .PP
 .SH RETURN VALUES
 .PP
@@ -120,4 +154,4 @@ is not properly mapped.
 Advice type is not supported.
 .SH "SEE ALSO"
 .BR lfs-ladvise (1),
-.BR liblustreapi (7)
+.BR lustreapi (7)