lustre/doc/llapi_get_fsname_instance.3

   1 .TH lustreapi 3 "2019 Jul 10" "Lustre User API"
   2 .SH NAME
   3 llapi_get_fsname_instance - get the client filesystem name and instance
   4 .br
   5 llapi_get_fsname - get the filesystem fsname from path
   6 .br
   7 llapi_get_instance - get the client filesystem instance from path
   8 .br
   9 llapi_getname - get the client filesystem identifier from path
  10 .SH SYNOPSIS
  11 .nf
  12 .B #include <sys/types.h>
  13 .B #include <sys/stat.h>
  14 .B #include <fcntl.h>
  15 .B #include <lustre/lustreapi.h>
  16 .sp
  17 .BI "int llapi_getname(const char *" path ", char *" name ", size_t " namelen );
  18 .sp
  19 .BI "int llapi_get_fsname_instance(const char *" path ", char *" fsname ,
  20 .BI                                     size_t " fsname_len" ", char *" instance ,
  21 .BI                                     size_t " instance_len" );
  22 .sp
  23 .BI "int llapi_get_fsname(const char *" path ", char *" fsname ,
  24 .BI                                     size_t " fsname_len" );
  25 .sp
  26 .BI "int llapi_get_instance(const char *" path ", char *" instance ,
  27 .BI                                     size_t " instance_len" );
  28 .SH DESCRIPTION
  29 .LP
  30 .B llapi_get_fsname_instance()
  31 retrieves the filesystem fsname and instance for the specified
  32 .I path
  33 and stores them in the
  34 .I fsname
  35 and
  36 .I instance
  37 buffers respectively, each of which can respectively hold at least
  38 .I fsname_len
  39 (at least
  40 .B LUSTRE_MAXFSNAME
  41 bytes), and
  42 .I instance_len
  43 (at least
  44 .B LUSTRE_MAXINSTANCE
  45 bytes).
  46 If only the fsname or instance identifier is needed, then the respective
  47 .BR llapi_get_fsname (3)
  48 or
  49 .BR llapi_get_instance (3)
  50 function can be used.  The
  51 .BR llapi_getname (3)
  52 function returns the combined
  53 .IR fsname - instance
  54 string.
  55 .P
  56 The filesystem
  57 .I fsname
  58 is a short name like
  59 .RB ' testfs '
  60 or
  61 .RB ' lfs2g '
  62 used to identify the filesystem on the clients and servers for mounting
  63 and configuration.  The
  64 .I instance
  65 is a client-unique temporary identifier like
  66 .RB ' ffff8803c9c0f000 '
  67 that differentiates multiple mounts of the same filesystem on the same
  68 client.  The instance is not guaranteed to be unique between different clients,
  69 nor is it expected to be the same for repeated mounts on the same client.
  70 .P
  71 The filesystem identifier is used in client-side parameters, like
  72 .BI mdc. fsname -MDT0000-mdc- instance .max_rpcs_in_flight
  73 for MDC and OSC devices, or
  74 .BI llite. fsname - instance .max_cached_mb
  75 and similar for llite tunable values and statistics.
  76 .SH RETURN VALUES
  77 .TP
  78 .B 0
  79 on success, or
  80 .TP
  81 -ve
  82 error code on failure and sets errno appropriately.
  83 .SH ERRORS
  84 .TP 15
  85 .SM EINVAL
  86 Invalid filesystem information found.
  87 .TP
  88 .SM ENAMETOOLONG
  89 The
  90 .IR fsname_len ,
  91 .IR instance_len ,
  92 or
  93 .I namelen
  94 buffer length was not large enough to hold the string.
  95 .SH SEE ALSO
  96 .BR lfs-getname (1),
  97 .BR lustreapi (7)