diff options
| author | Gabriel Schulhof <gabriel.schulhof@intel.com> | 2021-02-03 10:07:34 +0300 |
|---|---|---|
| committer | Gabriel Schulhof <gabriel.schulhof@intel.com> | 2021-02-10 10:34:30 +0300 |
| commit | ad3ebed046ef457530b046f2a62313a7e16b7e29 (patch) | |
| tree | 26a3e1308a5989eeb4c64dba0ffc99ece41ea784 /doc/api/n-api.md | |
| parent | 79d44baae28d64e0a0ee1765df3eb637e429e7a6 (diff) | |
node-api: allow retrieval of add-on file name
Unlike JS-only modules, native add-ons are always associated with a
dynamic shared object from which they are loaded. Being able to
retrieve its absolute path is important to native-only add-ons, i.e.
add-ons that are not themselves being loaded from a JS-only module
located in the same package as the native add-on itself.
Currently, the file name is obtained at environment construction time
from the JS `module.filename`. Nevertheless, the presence of `module`
is not required, because the file name could also be passed in via a
private property added onto `exports` from the `process.dlopen`
binding.
As an attempt at future-proofing, the file name is provided as a URL,
i.e. prefixed with the `file://` protocol.
Fixes: https://github.com/nodejs/node-addon-api/issues/449
PR-URL: https://github.com/nodejs/node/pull/37195
Co-authored-by: Michael Dawson <mdawson@devrus.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Diffstat (limited to 'doc/api/n-api.md')
| -rw-r--r-- | doc/api/n-api.md | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 5ae43e302fa..28ebc523e6e 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5958,6 +5958,31 @@ idempotent. This API may only be called from the main thread. +## Miscellaneous utilities + +## node_api_get_module_file_name + +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +```c +NAPI_EXTERN napi_status +node_api_get_module_file_name(napi_env env, const char** result); + +``` + +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: A URL containing the absolute path of the + location from which the add-on was loaded. For a file on the local + file system it will start with `file://`. The string is null-terminated and + owned by `env` and must thus not be modified or freed. + +`result` may be an empty string if the add-on loading process fails to establish +the add-on's file name during loading. + [ABI Stability]: https://nodejs.org/en/docs/guides/abi-stability/ [AppVeyor]: https://www.appveyor.com [C++ Addons]: addons.md |