lustre/doc/llapi_changelog_start.3

   1 .TH llapi_changelog_start 3 "2022-11-08" "" "Lustre User API"
   2 .SH NAME
   3 llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initialize and clean a read instance for MDT changelogs
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .PP
   8 .BI "int llapi_changelog_start(void **" priv ", enum changelog_send_flag " flags ,
   9 .BI "                          const char *" device ", long long " startrec ");"
  10 .PP
  11 .BI "int llapi_changelog_set_xflags(void *" priv,
  12 .BI "                               enum changelog_send_extra_flag " extra_flags ");"
  13 .PP
  14 .BI "int llapi_changelog_fini(void **" priv ");"
  15 .fi
  16 .SH DESCRIPTION
  17 .PP
  18 The function
  19 .B llapi_changelog_start()
  20 initializes a new instance
  21 .I priv
  22 to read MDT changelogs. It opens the changelog char device
  23 corresponding to the MDT's name given by
  24 .I device
  25 (e.g: "lustrefs-MDT0000").
  26 .br
  27 A changelog starting point can be specified with
  28 .I startrec
  29 record number.
  30 .B llapi_changelog_recv()
  31 will get changelog records with numbers greater or equal than
  32 .IR startrec .
  33 0 value means that all records will be read.
  34 .PP
  35 Some options can be passed to
  36 .B llapi_changelog_start()
  37 with
  38 .I flags
  39 mask.
  40 .PP
  41 .B enum changelog_send_flag
  42 values:
  43 .nf
  44 .LP
  45         CHANGELOG_FLAG_FOLLOW
  46         CHANGELOG_FLAG_BLOCK
  47         CHANGELOG_FLAG_JOBID
  48         CHANGELOG_FLAG_EXTRA_FLAGS
  49 .fi
  50 .TP
  51 CHANGELOG_FLAG_FOLLOW
  52 Use changelog follow mode:
  53 .B llapi_changelog_recv()
  54 will not return when all records have been read.  Instead it will block until a
  55 new record is available. It avoids restarting an instance and re-scan for newer
  56 changelogs.
  57 .TP
  58 CHANGELOG_FLAG_BLOCK
  59 Deprecated since Lustre 2.10.
  60 .TP
  61 CHANGELOG_FLAG_JOBID
  62 Pack jobid into the changelog records if available.
  63 .TP
  64 CHANGELOG_FLAG_EXTRA_FLAG
  65 Pack additional flag bits into the changelog record.
  66 .PP
  67 The function
  68 .B llapi_changelog_set_xflags()
  69 specifies additional changelog flags with
  70 .I extra_flags
  71 mask for the instance
  72 .IR priv .
  73 To use those extra flags, CHANGELOG_FLAG_EXTRA_FLAG must be set by
  74 .B llapi_changelog_start()
  75 on
  76 .I flags
  77 parameter.
  78 .PP
  79 .B enum changelog_send_extra_flag
  80 values:
  81 .nf
  82 .LP
  83         CHANGELOG_EXTRA_FLAG_UIDGID
  84         CHANGELOG_EXTRA_FLAG_NID
  85         CHANGELOG_EXTRA_FLAG_OMODE
  86         CHANGELOG_EXTRA_FLAG_XATTR
  87 .fi
  88 .TP
  89 CHANGELOG_EXTRA_FLAG_UIDGID
  90 Pack uid/gid into the changelog record
  91 .TP
  92 CHANGELOG_EXTRA_FLAG_NID
  93 Pack nid into the changelog record
  94 .TP
  95 CHANGELOG_EXTRA_FLAG_OMODE
  96 Pack open mode into the changelog record
  97 .TP
  98 CHANGELOG_EXTRA_FLAG_XATTR
  99 Pack xattr name into the changelog record
 100 .PP
 101 The function
 102 .B llapi_changelog_fini()
 103 closes the MDT's changelog char device and free internal pointers for the instance
 104 .IR priv .
 105 .SH RETURN VALUES
 106 .PP
 107 Return 0 on success or a negative errno value on failure.
 108 .SH ERRORS
 109 .TP 15
 110 .SM -ENOMEM
 111 Insufficient memory to complete operation.
 112 .TP
 113 .SM -EINVAL
 114 One or more invalid arguments are given.
 115 .TP
 116 .SM -ENOENT
 117 MDT's changelog char device not found. Is the Lustre FS mounted?
 118 .TP
 119 .SM -EACCES
 120 Not enough permissions to open the changelog char device. By default, the device
 121 is only accessible to the root user.
 122 .SH EXAMPLE
 123 An example can be found for in lfs.c source file.
 124 .B lfs_changelog()
 125 implements the following command:
 126 .br
 127 .BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]"
 128 .SH "SEE ALSO"
 129 .BR lfs-changelog (1),
 130 .BR llapi_changelog_clear (3)
 131 .BR llapi_changelog_get_fd (3),
 132 .BR llapi_changelog_in_buf (3),
 133 .BR llapi_changelog_recv (3),
 134 .BR lustreapi (7)