LLAPI\_LADVISE(3) Lustre Library Functions LLAPI\_LADVISE(3)

# [NAME](#NAME)

llapi\_ladvise - give IO advice/hints on a Lustre file to the server

# [SYNOPSIS](#SYNOPSIS)

```
#include <lustre/lustreapi.h>
```

```
int llapi_ladvise(int fd, unsigned long long flags,
                  int num_advise,
                  struct llapi_lu_ladvise *ladvise);
```

# [DESCRIPTION](#DESCRIPTION)

**llapi\_ladvise()** 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**](#LF_ASYNC)

Client returns to userspace immediately after submitting ladvise RPCs, leaving server threads to handle the advices asynchronously.

[**LF\_UNSET**](#LF_UNSET)

Unset/clear a previous advice (Currently only supports LU\_ADVISE\_LOCKNOEXPAND).

Each of the *ladvise* elements is an **llapi\_lu\_ladvise** structure, which contains the following fields:

```
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;
};
```

[*lla\_advice*](#lla_advice)

specifies the advice for the given file range, currently one of:

[**LU\_LADVISE\_WILLREAD**](#LU_LADVISE_WILLREAD)

Prefetch data into server cache using optimum I/O size for the server.

[**LU\_LADVISE\_DONTNEED**](#LU_LADVISE_DONTNEED)

Clean cached data for the specified file range(s) on the server.

[**LU\_LADVISE\_LOCKAHEAD**](#LU_LADVISE_LOCKAHEAD)

Request an LDLM extent lock of the given mode on the given byte range.

[**LU\_LADVISE\_NOEXPAND**](#LU_LADVISE_NOEXPAND)

Disable extent lock expansion behavior for I/O to this file descriptor.

[*lla\_start*](#lla_start)

is the offset in bytes for the start of this advice.

[*lla\_end*](#lla_end)

is the offset in bytes (non-inclusive) for the end of this advice.

[*lla\_value1*, *lla\_value2*, *lla\_value3*, *lla\_value4*](#lla_value1)

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.

[*lla\_lockahead\_mode*](#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.

[*lla\_peradvice\_flags*](#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.

[*lla\_lockahead\_result*](#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.

**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.

Typical usage of **llapi\_ladvise()** is to enable applications and users (via **lfs ladvise**(1)) 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 a net benefit. Fetching that data into each client cache with **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 [**posix\_fadvise**(2)](/man/enterprise-packages/lustre/posix_fadvise.2) and Linux [**fadvise**(2)](/man/enterprise-packages/lustre/fadvise.2) 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](#RETURN_VALUES)

**llapi\_ladvise()** return 0 on success, or -1 if an error occurred (in which case, errno is set appropriately).

# [ERRORS](#ERRORS)

[**ENOMEM**](#ENOMEM)

Insufficient memory to complete operation.

[**EINVAL**](#EINVAL)

One or more invalid arguments are given.

[**EFAULT**](#EFAULT)

memory region pointed by *ladvise* is not properly mapped.

[**EOPNOTSUPP**](#EOPNOTSUPP)

Advice type is not supported. Before Lustre 2.16, the NFS-specific error code was returned, but this does not print a useful error string.

# [AVAILABILITY](#AVAILABILITY)

**llapi\_ladvise()** is part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.9.0

# [SEE ALSO](#SEE_ALSO)

[**lfs-ladvise**(1)](/man/enterprise-packages/lustre/lfs-ladvise.1), [**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7)

2024-08-27 Lustre User API

---

Document: llapi_ladvise(3) from lustre 2.17.59-r1 (Chainguard OS)
Source: https://github.com/lustre/lustre-release