llapi_find_param_free(3)

LLAPI_FIND_PARAM_ALLOC(3)

Lustre Library Functions

LLAPI_FIND_PARAM_ALLOC(3)

NAME

llapi_find_param_alloc, llapi_find_param_free - allocate and free struct find_param objects.

SYNOPSIS

#include <lustre/lustreapi.h>

struct find_param *llapi_find_param_alloc(void);

void llapi_find_param_free(struct find_param *param);

llapi_find_param_alloc() returns a pointer to a newly-allocated struct find_param. The struct find_param contains the parameters that select which files match a search and how matching files are displayed. It may be used in subsequent calls to llapi_find(3), llapi_getstripe(3), and the other functions declared in <lustre/lustreapi.h> that take a struct find_param argument.

The returned struct find_param object is zero-filled; the caller sets the fields that describe the desired search before passing it to one of the functions listed above. Applications should obtain a struct find_param from llapi_find_param_alloc() rather than declaring one directly, so that the allocation always matches the size of the struct find_param used by the running library, even if the application was built against an older <lustre/lustreapi.h> header. The pointer should be freed with llapi_find_param_free() when it is no longer needed.

llapi_find_param_free() frees the memory associated with param, which must have been returned by an earlier call to llapi_find_param_alloc(). If param is NULL, no action is taken. Memory referenced by fields of the structure is not freed and remains owned by the caller. It should be used in preference to free(3) so that applications remain compatible with future versions of the library that may perform additional cleanup.

RETURN VALUES

llapi_find_param_alloc() returns a valid pointer on success or NULL on failure with errno set to an appropriate error code.

llapi_find_param_free() returns no value.

ERRORS

ENOMEM: Insufficient storage space is available.

EXAMPLES

List all regular files below path:

#include <lustre/lustreapi.h>
int find_regular_files(char *path)
{
	struct find_param *param;
	int rc;
	param = llapi_find_param_alloc();
	if (!param)
		return -errno;
	param->fp_max_depth = -1;
	param->fp_type = S_IFREG;
	rc = llapi_find(path, param);
	llapi_find_param_free(param);
	return rc;
}

AVAILABILITY

llapi_find_param_alloc() and llapi_find_param_free() are part of the lustre(7) user application interface library since release 2.18.0.