LLAPI_GET_DATA_VERSION(3)

NAME
llapi_get_data_version - fetch OST data version for a file

SYNOPSIS
#include <lustre/lustreapi.h>

int llapi_get_data_version(int fd, __u64 *data_version, __u64 flags);

DESCRIPTION
Fetch the combined data version for all OST objects associated with the open file handle.

The data version is the sum of the last committed transaction numbers of all data objects of a file for write() (or similar data modification), truncate() (or similar size modification) RPC in which an object's file data was modified. It does not track metadata operations on the file such as file permissions, ownership, etc. There is no guarantee that one data version is ordered compared to another, and should only be used for (in)equality comparison for a single file to check if its data objects were changed since the last data_version read.

The data version is typically used by data management engines such as HSM, OST object migration, and mirroring, primarily to verify that file data has not been changed concurrently by another process during a data movement or release operation.

Even when a cache flush is triggered on clients accessing this file, race conditions are possible and the data version should be checked before and after data management operations to ensure the data did not change concurrently. This allows data management operations to avoid blocking application file IO, while maintaining data consistency during data copy or migration.

fd  open file descriptor

data_version
    pointer to 64-bit integer to store the file version.

flags
    flags that affect whether cached file data on clients is flushed before fetching the data version. Flags may have the following values:

LL_DV_RD_FLUSH
    OSTs will take a read lock to flush dirty pages of fd from clients.

LL_DV_WR_FLUSH
    OSTs will take a write lock to flush all cache pages of fd from clients.

LL_DV_SZ_UPDATE
    Update the file size on the client

RETURN VALUES
llapi_get_data_version() returns:

0   on success and data_version contains the file's object data version, or zero if no objects are initialized for this file.

<0  a negative errno value on failure

EXAMPLES
    	int fd_src;
    	__u64 dv1, dv2;

    again:
    	fd_src = open(filename, O_RDONLY);
    	rc = llapi_get_data_version(fd_src, &dv1, 0);
    	/* perform some data copy operation */
    	rc = llapi_get_data_version(fd_src, &dv2, LL_DV_RD_FLUSH);
            close(fd_src);
    	if (dv1 != dv2) {
    		rc = -EAGAIN;
    		fprintf(stderr, "%s: %s changed during copy, retrying,
                            progname, filename);
    		goto again;
    	}

AVAILABILITY
The llapi_get_data_version() API is part of the lustre(7) user application interface library since release 2.3.0.

SEE ALSO
lfs-data_version(1), lfs-migrate(1), llapi_fswap_layouts(3), llapi_fsync(3), llapi_get_data_version(3), lustre(7), lustreapi(7)