lustre/doc/llapi_param_get_value.3

   1 .TH llapi_param_get_value 3 "2020 Feb 24" "Lustre User API"
   2 .SH NAME
   3 llapi_param_get_value \- read parameter files for Lustre to a buffer
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .sp
   8 .BI "int llapi_param_get_value(const char "  "*path"  ", char " "**buf" \
   9 ", size_t " "*buflen" ");"
  10 .SH DESCRIPTION
  11 .LP
  12 The
  13 .B llapi_param_get_value()
  14 function reads the contents of files in procfs, sysfs, etc. into a buffer.
  15 If the buffer is preallocated, it will have a fixed size.
  16 If the buffer is not preallocated, it will be automatically sized to fit
  17 the contents of the file. There is also an option to query the size of a file.
  18
  19 The behavior of
  20 .B llapi_param_get_value()
  21 depends on the value of
  22 .IR buf .
  23 If
  24 .I buf
  25 is NULL, then the contents of
  26 .I path
  27 will not be saved into
  28 .IR *buf ,
  29 but the number of bytes needed to hold the file will be stored in
  30 .IR buflen .
  31 This size will include the space needed for the NUL terminating byte.
  32 However, the size of the file can change because it is dynamically generated.
  33 This means that it's possible for the file size to increase which will cause
  34 the value stored in
  35 .I buflen
  36 to still not be large enough when used in a subsequent call.
  37 .sp
  38 If
  39 .I buf
  40 is not NULL but
  41 .I *buf
  42 is NULL, then
  43 .I *buf
  44 will point to an automatically allocated buffer that will hold the contents of
  45 .IR path ,
  46 and buflen will hold the number of bytes written excluding the NUL terminating
  47 byte.
  48 .sp
  49 If both
  50 .I buf
  51 and
  52 .I *buf
  53 are not NULL, then
  54 .I buf
  55 is assumed to be a pre-allocated buffer of
  56 .I *buflen
  57 size. The files contents will be put into
  58 .I *buf
  59 and the number of bytes written to
  60 .IR *buflen ,
  61 excluding the NUL terminating byte. In the case that
  62 .I buflen
  63 is too small to hold the NUL-terminated contents of the file,
  64 .I buflen
  65 will contain a suggested size for
  66 .IR *buf .
  67 This suggested size includes the NUL terminating byte, just as in the case where
  68 .I buf
  69 is NULL.
  70
  71 .SH RETURN VALUES
  72 .TP
  73 .B 0
  74 on success
  75 .TP
  76 -ve
  77 error code on failure and sets errno appropriately.
  78
  79 .SH ERRORS
  80 .TP
  81 -EINVAL
  82 if either
  83 .I path
  84 or
  85 .I buflen
  86 are NULL.
  87 .TP
  88 -EOVERFLOW
  89 if
  90 .I buf
  91 and
  92 .I *buf
  93 are not NULL, and the pre-allocated buffer is too small.
  94 .TP
  95 -ENOMEM
  96 if
  97 .I buf
  98 is not NULL, but the buffer allocation failed
  99
 100 .SH SEE ALSO
 101 .BR llapi_get_param_paths (3),
 102 .BR lustreapi (7),
 103 .BR lctl-get_param (8)