--- name: "fi_provider" section: "3" platform: "linux" package: "libfabric" version: "2.7.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fi_provider" --- # fi\_provider(3) External provider entry point ## NAME fi\_prov\_ini - External provider entry point - fi\_param\_define / fi\_param\_get Register and retrieve environment variables with the libfabric core - fi\_log\_enabled / fi\_log\_ready / fi\_log Control and output debug logging information. - fi\_open / fi\_import / fi\_close Open and import a named library object - fi\_import\_log Import new logging callbacks ## SYNOPSIS - ``` #include #include struct fi_provider* fi_prov_ini(void); int fi_param_define(const struct fi_provider *provider, const char *param_name, enum fi_param_type type, const char *help_string_fmt, ...); int fi_param_get_str(struct fi_provider *provider, const char *param_name, char **value); int fi_param_get_int(struct fi_provider *provider, const char *param_name, int *value); int fi_param_get_bool(struct fi_provider *provider, const char *param_name, int *value); int fi_param_get_size_t(struct fi_provider *provider, const char *param_name, size_t *value); ``` - ``` #include #include #include int fi_log_enabled(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys); int fi_log_ready(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys, uint64_t *showtime); void fi_log(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys, const char *func, int line, const char *fmt, ...); ``` - ``` #include int fi_open(uint32_t version, const char *name, void *attr, size_t attr_len, uint64_t flags, struct fid **fid, void *context); static inline int fi_import(uint32_t version, const char *name, void *attr, size_t attr_len, uint64_t flags, struct fid *fid, void *context); int fi_close(struct fid *fid); ``` - ``` #include #include static inline int fi_import_log(uint32_t version, uint64_t flags, struct fid_logging *log_fid); ``` ## ARGUMENTS - *provider* Reference to the provider. - *version* API version requested by application. - *name* Well-known name of the library object to open. - *attr* Optional attributes of object to open. - *attr\_len* Size of any attribute structure passed to fi\_open. Should be 0 if no attributes are give. - *fid* Returned fabric identifier for opened object. ## DESCRIPTION A fabric provider implements the application facing software interfaces needed to access network specific protocols, drivers, and hardware. The interfaces and structures defined by this man page are exported by the libfabric library, but are targeted for provider implementations, rather than for direct use by most applications. Integrated providers are those built directly into the libfabric library itself. External providers are loaded dynamically by libfabric at initialization time. External providers must be in a standard library path or in the libfabric library search path as specified by environment variable. Additionally, external providers must be named with the suffix “-fi.so” at the end of the name. Named objects are special purpose resources which are accessible directly to applications. They may be used to enhance or modify the behavior of library core. For details, see the fi\_open call below. ### fi\_prov\_ini This entry point must be defined by external providers. On loading, libfabric will invoke fi\_prov\_ini() to retrieve the provider’s fi\_provider structure. Additional interactions between the libfabric core and the provider will be through the interfaces defined by that struct. ### fi\_param\_define Defines a configuration parameter for use by a specified provider. The help\_string and param\_name arguments must be non-NULL, help\_string must additionally be non-empty. They are copied internally and may be freed after calling fi\_param\_define. ### fi\_param\_get Gets the value of a configuration parameter previously defined using fi\_param\_define(). The value comes from the environment variable name of the form FI\_\_, all converted to upper case. If the parameter was previously defined and the user set a value, FI\_SUCCESS is returned and (\*value) points to the retrieved value. If the parameter name was previously defined, but the user did not set a value, -FI\_ENODATA is returned and the value of (\*value) is unchanged. If the parameter name was not previously defined via fi\_param\_define(), -FI\_ENOENT will be returned and the value of (\*value) is unchanged. If the value in the environment is not valid for the parameter type, -FI\_EINVAL will be returned and the value of (\*value) is unchanged. ### fi\_log\_enabled / fi\_log\_ready / fi\_log These functions control debug and informational logging output. Providers typically access these functions through the FI\_LOG and related macros in fi\_log.h and do not call these function directly. ### fi\_open Open a library resource using a well-known name. This feature allows applications and providers a mechanism which can be used to modify or enhance core library services and behavior. The details are specific based on the requested object name. Most applications will not need this level of control. The library API version known to the application should be provided through the version parameter. The use of attributes is object dependent. If required, attributes should be provided through the attr parameter, with attr\_len set to the size of the referenced attribute structure. The following is a list of published names, along with descriptions of the service or resource to which they correspond. - *mr\_cache* The mr\_cache object references the internal memory registration cache used by the different providers. Additional information on the cache is available in the [fi\_mr(3)](/fi_mr/3.md) man page. - *logging* The logging object references the internal logging subsystem used by the different providers. Once opened, custom logging callbacks may be installed. Can be opened only once and only the last import is used if imported multiple times. ### fi\_import This helper function is a combination of fi\_open and fi\_import\_fid. It may be used to import a fabric object created and owned by the libfabric user. This allows the upper level libraries or the application to override or define low-level libfabric behavior. ### fi\_import\_log Helper function to override the low-level libfabric’s logging system with new callback functions. - ``` struct fi_ops_log { size_t size; int (*enabled)(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys, uint64_t flags); int (*ready)(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys, uint64_t flags, uint64_t *showtime); void (*log)(const struct fi_provider *prov, enum fi_log_level level, enum fi_log_subsys subsys, const char *func, int line, const char *msg); }; struct fid_logging { struct fid fid; struct fi_ops_log *ops; }; ``` ## PROVIDER INTERFACE The fi\_provider structure defines entry points for the libfabric core to use to access the provider. All other calls into a provider are through function pointers associated with allocated objects. - ``` struct fi_provider { uint32_t version; uint32_t fi_version; struct fi_context context; const char *name; int (*getinfo)(uint32_t version, const char *node, const char *service, uint64_t flags, const struct fi_info *hints, struct fi_info **info); int (*fabric)(struct fi_fabric_attr *attr, struct fid_fabric **fabric, void *context); void (*cleanup)(void); }; ``` ### version The provider version. For providers integrated with the library, this is often the same as the library version. ### fi\_version The library interface version that the provider was implemented against. The provider’s fi\_version must be greater than or equal to an application’s requested api version for the application to use the provider. It is a provider’s responsibility to support older versions of the api if it wishes to supports legacy applications. For integrated providers ## RETURN VALUE Returns FI\_SUCCESS on success. On error, a negative value corresponding to fabric errno is returned. Fabric errno values are defined in rdma/fi\_errno.h. ## SEE ALSO [fabric(7)](/fabric/7.md), [fi\_getinfo(3)](/fi_getinfo/3.md) [fi\_mr(3)](/fi_mr/3.md), ## AUTHORS OpenFabrics.