diff --git a/doc/api/process.md b/doc/api/process.md index e24bf19d9d2f44..82edcf9436c8eb 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -638,6 +638,48 @@ process's [`ChildProcess.disconnect()`][]. If the Node.js process was not spawned with an IPC channel, `process.disconnect()` will be `undefined`. +## process.dlopen(module, filename[, flags]) + + +* `module` {Object} +* `filename` {string} +* `flags` {os.constants.dlopen}. Defaults to `os.constants.dlopen.RTLD_LAZY`. + +The `process.dlopen()` method allows to dynamically load shared +objects. It is primarily used by `require()` to load +C++ Addons, and should not be used directly, except in special +cases. In other words, [`require()`][] should be preferred over +`process.dlopen()`, unless there are specific reasons. + +The `flags` argument is an integer that allows to specify dlopen +behavior. See the [`os.constants.dlopen`][] documentation for details. + +If there are specific reasons to use `process.dlopen()` (for instance, +to specify dlopen flags), it's often useful to use [`require.resolve()`][] +to look up the module's path. + +*Note*: An important drawback when calling `process.dlopen()` is that the +`module` instance must be passed. Functions exported by the C++ Addon will +be accessible via `module.exports`. + +The example below shows how to load a C++ Addon, named as `binding`, +that exports a `foo` function. All the symbols will be loaded before +the call returns, by passing the `RTLD_NOW` constant. In this example +the constant is assumed to be available. + +```js +const os = require('os'); +process.dlopen(module, require.resolve('binding'), + os.constants.dlopen.RTLD_NOW); +module.exports.foo(); +``` + ## process.emitWarning(warning[, options])