1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>erl_ddll</title>
32
<module>erl_ddll</module>
33
<modulesummary>Dynamic Driver Loader and Linker</modulesummary>
35
<p>The <c>erl_ddll</c> module provides an interface for loading
36
and unloading <em>erlang linked in drivers</em> in runtime.</p>
38
<p>This is a large reference document. For casual use of the
39
module, as well as for most real world applications, the
40
descriptions of the functions <seealso marker="#load/2">load/2</seealso> and <seealso marker="#unload/1">unload/1</seealso> are enough to get
43
<p>The driver should be provided as a dynamically linked library
44
in a object code format specific for the platform in use,
45
i. e. <c>.so</c> files on most Unix systems and <c>.ddl</c>
46
files on windows. An erlang linked in driver has to provide
47
specific interfaces to the emulator, so this module is not
48
designed for loading arbitrary dynamic libraries. For further
49
information about erlang drivers, refer to the ERTS reference
50
manual section <seealso marker="erts:erl_driver">erl_driver</seealso>.</p>
51
<marker id="users"></marker>
52
<p>When describing a set of functions, (i.e. a module, a part of a
53
module or an application) executing in a process and wanting to
54
use a ddll-driver, we use the term <em>user</em>. There can be
55
several users in one process (different modules needing the same
56
driver) and several processes running the same code, making up
57
several <em>users</em> of a driver. In the basic scenario, each
58
user loads the driver before starting to use it and unloads the
59
driver when done. The reference counting keeps track of
60
processes as well as the number of loads by each process, so that
61
the driver will only be unloaded when no one wants it
62
(it has no user). The driver also keeps track of ports that are
63
opened towards it, so that one can delay unloading until all
64
ports are closed or kill all ports using the driver when it is
66
<marker id="scenarios"></marker>
67
<p>The interface supports two basic scenarios of loading and
68
unloading. Each scenario can also have the option of either
69
killing ports when the driver is unloading, or waiting for the
70
ports to close themselves. The scenarios are:</p>
72
<tag><em>Load and unload on a "when needed basis"</em></tag>
74
<p>This (most common) scenario simply supports that each
75
<seealso marker="#users">user</seealso> of the driver loads
76
it when it is needed and unloads it when the <seealso marker="#users">user</seealso> no longer have any use for
77
it. The driver is always reference counted and as long as a
78
process keeping the driver loaded is still alive, the driver
79
is present in the system.</p>
80
<p>Each <seealso marker="#users">user</seealso> of the driver
81
use <em>literally</em> the same pathname for the driver when
82
demanding load, but the <seealso marker="#users">users</seealso> are not really concerned
83
with if the driver is already loaded from the filesystem or
84
if the object code has to be loaded from filesystem.</p>
85
<p>Two pairs of functions support this scenario:</p>
87
<tag><em>load/2 and unload/1</em></tag>
89
<p>When using the <c>load/unload</c> interfaces, the
90
driver will not <em>actually</em> get unloaded until the
91
<em>last port</em> using the driver is closed. The function
92
<c>unload/1</c> can return immediately, as the <seealso marker="#users">users</seealso> are not really concerned
93
with when the actual unloading occurs. The
94
driver will actually get unloaded when no one needs it any longer.</p>
95
<p>If a process having the driver loaded dies, it will have
96
the same effect as if unloading was done. </p>
97
<p>When loading, the function <c>load/2</c> returns
98
<c>ok</c> as soon as there is any instance of the driver
99
present, so that if a driver is waiting to get unloaded
100
(due to open ports), it will simply change state to no
101
longer need unloading.</p>
103
<tag><em>load_driver/2 and unload_driver/1</em></tag>
105
<p>These interfaces is intended to be used when it is considered an
106
error that ports are open towards a driver that no <seealso marker="#users">user</seealso>
107
has loaded. The ports still open when the
108
last <seealso marker="#users">user</seealso> calls
109
<c>unload_driver/1</c> or when the last process having the
110
driver loaded dies, will get killed with reason
111
<c>driver_unloaded</c>.</p>
112
<p>The function names <c>load_driver</c> and
113
<c>unload_driver</c> are kept for backward
118
<tag><em>Loading and reloading for code replacement</em></tag>
120
<p>This scenario occurs when the driver code might need
121
replacement during operation of the Erlang
122
emulator. Implementing driver code replacement is somewhat
123
more tedious than beam code replacement, as one driver
124
cannot be loaded as both "old" and "new" code. All <seealso marker="#users">users</seealso> of a driver must have it
125
closed (no open ports) before the old code can be unloaded
126
and the new code can be loaded.</p>
127
<p>The actual unloading/loading is done as one atomic
128
operation, blocking all processes in the system from using
129
the driver concerned while in progress.</p>
130
<p>The preferred way to do driver code replacement is to let
131
<em>one single process</em> keep track of the driver. When
132
the process start, the driver is loaded. When replacement
133
is required, the driver is reloaded. Unload is probably never
134
done, or done when the process exits. If more than one <seealso marker="#users">user</seealso> has a driver loaded when code
135
replacement is demanded, the replacement cannot occur until
136
the last "other" <seealso marker="#users">user</seealso> has
137
unloaded the driver.</p>
138
<p>Demanding reload when a reload is already in progress is
139
always an error. Using the high level functions, it is also
140
an error to demand reloading when more than one <seealso marker="#users">user</seealso> has the driver loaded. To
141
simplify driver replacement, avoid designing your system so
142
that more than than one <seealso marker="#users">user</seealso> has the driver loaded.</p>
143
<p>The two functions for reloading drivers should be used
144
together with corresponding load functions, to support the two
145
different behaviors concerning open ports:</p>
147
<tag><em>load/2 and reload/2</em></tag>
149
<p>This pair of functions is used when reloading should be
150
done after the last open port towards the driver is
152
<p>As <c>reload/2</c> actually waits for the reloading to
153
occur, a misbehaving process keeping open ports towards
154
the driver (or keeping the driver loaded) might cause
155
infinite waiting for reload. Timeouts has to be provided
156
outside of the process demanding the reload or by using
157
the low-level interface <seealso marker="#try_load/3">try_load/3</seealso> in combination
158
with driver monitors (see below).</p>
160
<tag><em>load_driver/2 and reload_driver/2</em></tag>
162
<p>This pair of functions are used when open ports towards
163
the driver should be killed with reason
164
<c>driver_unloaded</c> to allow for new driver code to
166
<p>If, however, another process has the driver loaded,
167
calling <c>reload_driver</c> returns the error code
168
<c>pending_process</c>. As stated earlier,
169
the recommended design is to not allow other <seealso marker="#users">users</seealso> than the "driver
170
reloader" to actually demand loading of the concerned
179
<name>demonitor(MonitorRef) -> ok</name>
180
<fsummary>Remove a monitor for a driver</fsummary>
182
<v>MonitorRef = ref()</v>
185
<p>Removes a driver monitor in much the same way as
186
<seealso marker="erlang#erlang:demonitor/1">erlang:demonitor/1</seealso> does with process
187
monitors. See <seealso marker="#monitor/2">monitor/2</seealso>, <seealso marker="#try_load/3">try_load/3</seealso> and <seealso marker="#try_unload/2">try_unload/2</seealso> for details
188
about how to create driver monitors.</p>
189
<p>The function throws a <c>badarg</c> exception if the
190
parameter is not a ref(). </p>
194
<name>info() -> AllInfoList</name>
195
<fsummary>Retrieve information about all drivers</fsummary>
197
<v>AllInfoList = [ DriverInfo ]</v>
198
<v>DriverInfo = {DriverName, InfoList}</v>
199
<v>DriverName = string()</v>
200
<v>InfoList = [ InfoItem ]</v>
201
<v>InfoItem = {Tag, Value}</v>
203
<v>Value = term()</v>
206
<p>Returns a list of tuples <c>{DriverName, InfoList}</c>, where
207
<c>InfoList</c> is the result of calling <seealso marker="#info/1">info/1</seealso> for that
208
<c>DriverName</c>. Only dynamically linked in drivers are
209
included in the list.</p>
213
<name>info(Name) -> InfoList</name>
214
<fsummary>Retrieve information about one driver</fsummary>
216
<v>Name = string() | atom()</v>
217
<v>InfoList = [ InfoItem ]</v>
218
<v>InfoItem = {Tag, Value}</v>
220
<v>Value = term()</v>
223
<p>Returns a list of tuples <c>{Tag, Value}</c>, where
224
<c>Tag</c> is the information item and <c>Value</c> is the result
225
of calling <seealso marker="#info/2">info/2</seealso> with this driver name and
226
this tag. The result being a tuple list containing all
227
information available about a driver. </p>
228
<p>The different tags that will appear in the list are:</p>
229
<list type="bulleted">
230
<item>processes</item>
231
<item>driver_options</item>
232
<item>port_count</item>
233
<item>linked_in_driver</item>
234
<item>permanent</item>
235
<item>awaiting_load</item>
236
<item>awaiting_unload</item>
238
<p>For a detailed description of each value, please read the
239
description of <seealso marker="#info/2">info/2</seealso> below.</p>
240
<p>The function throws a <c>badarg</c> exception if the driver
241
is not present in the system.</p>
245
<name>info(Name, Tag) -> Value</name>
246
<fsummary>Retrieve specific information about one driver</fsummary>
248
<v>Name = string() | atom()</v>
249
<v>Tag = processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload</v>
250
<v>Value = term()</v>
253
<p>This function returns specific information about one aspect
254
of a driver. The <c>Tag</c> parameter specifies which aspect
255
to get information about. The <c>Value</c> return differs
256
between different tags:</p>
258
<tag><em>processes</em></tag>
260
<p>Return all processes containing <seealso marker="#users">users</seealso> of the specific drivers
261
as a list of tuples <c>{pid(),int()}</c>, where the
262
<c>int()</c> denotes the number of users in the process
265
<tag><em>driver_options</em></tag>
267
<p>Return a list of the driver options provided when
268
loading, as well as any options set by the driver itself
269
during initialization. The currently only valid option
270
being <c>kill_ports</c>.</p>
272
<tag><em>port_count</em></tag>
274
<p>Return the number of ports (an <c>int()</c>) using the driver.</p>
276
<tag><em>linked_in_driver</em></tag>
278
<p>Return a <c>bool()</c>, being <c>true</c> if the driver is a
279
statically linked in one and <c>false</c> otherwise.</p>
281
<tag><em>permanent</em></tag>
283
<p>Return a <c>bool()</c>, being <c>true</c> if the driver has made
284
itself permanent (and is <em>not</em> a statically
285
linked in driver). <c>false</c> otherwise.</p>
287
<tag><em>awaiting_load</em></tag>
289
<p>Return a list of all processes having monitors for
290
<c>loading</c> active, each process returned as
291
<c>{pid(),int()}</c>, where the <c>int()</c> is the
292
number of monitors held by the process <c>pid()</c>.</p>
294
<tag><em>awaiting_unload</em></tag>
296
<p>Return a list of all processes having monitors for
297
<c>unloading</c> active, each process returned as
298
<c>{pid(),int()}</c>, where the <c>int()</c> is the
299
number of monitors held by the process <c>pid()</c>.</p>
302
<p>If the options <c>linked_in_driver</c> or <c>permanent</c>
303
return true, all other options will return the value
304
<c>linked_in_driver</c> or <c>permanent</c> respectively.</p>
305
<p>The function throws a <c>badarg</c> exception if the driver
306
is not present in the system or the tag is not supported.</p>
310
<name>load(Path, Name) -> ok | {error, ErrorDesc}</name>
311
<fsummary>Load a driver</fsummary>
313
<v>Path = Name = string() | atom()</v>
314
<v>ErrorDesc = term()</v>
317
<p>Loads and links the dynamic driver <c>Name</c>. <c>Path</c>
318
is a file path to the directory containing the driver.
319
<c>Name</c> must be a sharable object/dynamic library. Two
320
drivers with different <c>Path</c> parameters cannot be
321
loaded under the same name. The <c>Name</c> is a string or
322
atom containing at least one character.</p>
323
<p>The <c>Name</c> given should correspond to the filename
324
of the actual dynamically loadable object file residing in
325
the directory given as <c>Path</c>, but <em>without</em> the
326
extension (i.e. <c>.so</c>). The driver name provided in
327
the driver initialization routine must correspond with the
328
filename, in much the same way as erlang module names
329
correspond to the names of the <c>.beam</c> files.</p>
330
<p>If the driver has been previously unloaded, but is still
331
present due to open ports against it, a call to
332
<c>load/2</c> will stop the unloading and keep the driver
333
(as long as the <c>Path</c> is the same) and <c>ok</c> is
334
returned. If one actually wants the object code to be
335
reloaded, one uses <seealso marker="#reload/2">reload/2</seealso> or the low-level
336
interface <seealso marker="#try_load/3">try_load/3</seealso>
337
instead. Please refer to the description of <seealso marker="#scenarios">different scenarios</seealso> for
338
loading/unloading in the introduction.</p>
339
<p>If more than one process tries to load an already loaded
340
driver withe the same <c>Path</c>, or if the same process
341
tries to load it several times, the function will return
342
<c>ok</c>. The emulator will keep track of the
343
<c>load/2</c> calls, so that a corresponding number of
344
<c>unload/2</c> calls will have to be done from the same
345
process before the driver will actually get unloaded. It is
346
therefore safe for an application to load a driver that is
347
shared between processes or applications when needed. It can
348
safely be unloaded without causing trouble for other
349
parts of the system. </p>
350
<p>It is not allowed to load
351
several drivers with the same name but with different
352
<c>Path</c> parameters.</p>
354
<p>Note especially that the <c>Path</c> is interpreted
355
literally, so that all loaders of the same driver needs to
356
give the same <em>literal</em><c>Path</c> string, even
357
though different paths might point out the same directory
358
in the filesystem (due to use of relative paths and
361
<p>On success, the function returns <c>ok</c>. On
362
failure, the return value is <c>{error,ErrorDesc}</c>,
363
where <c>ErrorDesc</c> is an opaque term to be
364
translated into human readable form by the <seealso marker="#format_error/1">format_error/1</seealso>
366
<p>For more control over the error handling, again use the
367
<seealso marker="#try_load/3">try_load/3</seealso>
368
interface instead.</p>
369
<p>The function throws a <c>badarg</c> exception if the
370
parameters are not given as described above. </p>
374
<name>load_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
375
<fsummary>Load a driver</fsummary>
377
<v>Path = Name = string() | atom()</v>
378
<v>ErrorDesc = term()</v>
381
<p>Works essentially as <c>load/2</c>, but will load the driver
382
with options other options. All ports that are using the
383
driver will get killed with the reason
384
<c>driver_unloaded</c> when the driver is to be unloaded.</p>
385
<p>The number of loads and unloads by different <seealso marker="#users">users</seealso> influence the actual loading
386
and unloading of a driver file. The port killing will
387
therefore only happen when the <em>last</em><seealso marker="#users">user</seealso> unloads the driver, or the
388
last process having loaded the driver exits.</p>
389
<p>This interface (or at least the name of the functions) is
390
kept for backward compatibility. Using <seealso marker="#try_load/3">try_load/3</seealso> with
391
<c>{driver_options,[kill_ports]} </c> in the option list will
392
give the same effect regarding the port killing.</p>
393
<p>The function throws a <c>badarg</c> exception if the
394
parameters are not given as described above. </p>
398
<name>monitor(Tag, Item) -> MonitorRef</name>
399
<fsummary>Create a monitor for a driver</fsummary>
402
<v>Item = {Name, When}</v>
403
<v>Name = atom() | string()</v>
404
<v>When = loaded | unloaded | unloaded_only</v>
405
<v>MonitorRef = ref()</v>
408
<p>This function creates a driver monitor and works in many
409
ways as the function <seealso marker="erlang#erlang:monitor/2">erlang:monitor/2</seealso>,
410
does for processes. When a driver changes state, the monitor
411
results in a monitor-message being sent to the calling
412
process. The <c>MonitorRef</c> returned by this function is
413
included in the message sent.</p>
414
<p>As with process monitors, each driver monitor set will only
415
generate <em>one single message</em>. The monitor is
416
"destroyed" after the message is sent and there is then no
417
need to call <seealso marker="#demonitor/1">demonitor/1</seealso>.</p>
418
<p>The <c>MonitorRef</c> can also be used in subsequent calls
419
to <seealso marker="#demonitor/1">demonitor/1</seealso> to
420
remove a monitor.</p>
421
<p>The function accepts the following parameters:</p>
423
<tag><em>Tag</em></tag>
425
<p>The monitor tag is always <c>driver</c> as this function
426
can only be used to create driver monitors. In the future,
427
driver monitors will be integrated with process monitors,
428
why this parameter has to be given for consistence.</p>
430
<tag><em>Item</em></tag>
432
<p>The <c>Item</c> parameter specifies which driver one
433
wants to monitor (the name of the driver) as well as
434
which state change one wants to monitor. The parameter
435
is a tuple of arity two whose first element is the
436
driver name and second element is either of:</p>
438
<tag><em>loaded</em></tag>
440
<p>Notify me when the driver is reloaded (or loaded if
441
loading is underway). It only makes sense to monitor
442
drivers that are in the process of being loaded or
443
reloaded. One cannot monitor a future-to-be driver
444
name for loading, that will only result in a
445
<c>'DOWN'</c> message being immediately sent.
446
Monitoring for loading is therefore most useful when
447
triggered by the <seealso marker="#try_load/3">try_load/3</seealso> function,
448
where the monitor is created <em>because</em> the
449
driver is in such a pending state.</p>
450
<p>Setting a driver monitor for <c>loading</c> will
451
eventually lead to one of the following messages
454
<tag><em>{'UP', ref(), driver, Name, loaded}</em></tag>
456
<p>This message is sent, either immediately if the
457
driver is already loaded and no reloading is
458
pending, or when reloading is executed if
459
reloading is pending. </p>
460
<p>The <seealso marker="#users">user</seealso> is
461
expected to know if reloading is demanded prior
462
to creating a monitor for loading.</p>
464
<tag><em>{'UP', ref(), driver, Name, permanent}</em></tag>
466
<p>This message will be sent if reloading was
467
expected, but the (old) driver made itself
468
permanent prior to reloading. It will also be
469
sent if the driver was permanent or statically
470
linked in when trying to create the monitor.</p>
472
<tag><em>{'DOWN', ref(), driver, Name, load_cancelled}</em></tag>
474
<p>This message will arrive if reloading was
475
underway, but the <seealso marker="#users">user</seealso> having requested
476
reload cancelled it by either dying or calling
477
<seealso marker="#try_unload/2">try_unload/2</seealso>
478
(or <c>unload/1</c>/<c>unload_driver/1</c>)
479
again before it was reloaded.</p>
481
<tag><em>{'DOWN', ref(), driver, Name, {load_failure, Failure}}</em></tag>
483
<p>This message will arrive if reloading was
484
underway but the loading for some reason
485
failed. The <c>Failure</c> term is one of the
486
errors that can be returned from <seealso marker="#try_load/3">try_load/3</seealso>. The
487
error term can be passed to <seealso marker="#format_error/1">format_error/1</seealso>
488
for translation into human readable form. Note
489
that the translation has to be done in the same
490
running erlang virtual machine as the error
495
<tag><em>unloaded</em></tag>
497
<p>Monitor when a driver gets unloaded. If one
498
monitors a driver that is not present in the system,
499
one will immediately get notified that the driver got
500
unloaded. There is no guarantee that the driver was
501
actually ever loaded.</p>
502
<p>A driver monitor for unload will eventually result
503
in one of the following messages being sent:</p>
505
<tag><em>{'DOWN', ref(), driver, Name, unloaded}</em></tag>
507
<p>The driver instance monitored is now
508
unloaded. As the unload might have been due to a
509
<c>reload/2</c> request, the driver might once
510
again have been loaded when this message
513
<tag><em>{'UP', ref(), driver, Name, unload_cancelled}</em></tag>
515
<p>This message will be sent if unloading was
516
expected, but while the driver was waiting for
517
all ports to get closed, a new <seealso marker="#users">user</seealso> of the driver
518
appeared and the unloading was cancelled.</p>
519
<p>This message appears when an <c>{ok, pending_driver}</c>) was returned from <seealso marker="#try_unload/2">try_unload/2</seealso>)
520
for the last <seealso marker="#users">user</seealso> of the driver and
521
then a <c>{ok, already_loaded}</c> is returned
522
from a call to <seealso marker="#try_load/3">try_load/3</seealso>.</p>
523
<p>If one wants to <em>really</em> monitor when the
524
driver gets unloaded, this message will distort
525
the picture, no unloading was really done.
526
The <c>unloaded_only</c> option creates a monitor
527
similar to an <c>unloaded</c> monitor, but does
528
never result in this message.</p>
530
<tag><em>{'UP', ref(), driver, Name, permanent}</em></tag>
532
<p>This message will be sent if unloading was
533
expected, but the driver made itself
534
permanent prior to unloading. It will also be
535
sent if trying to monitor a permanent or
536
statically linked in driver.</p>
540
<tag><em>unloaded_only</em></tag>
542
<p>A monitor created as <c>unloaded_only</c> behaves
543
exactly as one created as <c>unloaded</c> with the
544
exception that the <c>{'UP', ref(), driver, Name, unload_cancelled}</c> message will never be
545
sent, but the monitor instead persists until the
546
driver <em>really</em> gets unloaded.</p>
551
<p>The function throws a <c>badarg</c> exception if the
552
parameters are not given as described above. </p>
556
<name>reload(Path, Name) -> ok | {error, ErrorDesc}</name>
557
<fsummary>Replace a driver</fsummary>
559
<v>Path = Name = string() | atom()</v>
560
<v>ErrorDesc = pending_process | OpaqueError</v>
561
<v>OpaqueError = term()</v>
564
<p>Reloads the driver named <c>Name</c> from a possibly
565
different <c>Path</c> than was previously used. This
566
function is used in the code change <seealso marker="#scenarios">scenario</seealso> described in the
568
<p>If there are other <seealso marker="#users">users</seealso>
569
of this driver, the function will return <c>{error, pending_process}</c>, but if there are no more users, the
570
function call will hang until all open ports are closed.</p>
573
several <seealso marker="#users">users</seealso>
574
with driver reload requests.</p>
576
<p>If one wants to avoid hanging on open ports, one should use
577
the <seealso marker="#try_load/3">try_load/3</seealso>
578
function instead.</p>
579
<p>The <c>Name</c> and <c>Path</c> parameters have exactly the
580
same meaning as when calling the plain <seealso marker="#load/2">load/2</seealso> function.</p>
583
several <seealso marker="#users">users</seealso>
584
with driver reload requests.</p>
586
<p>On success, the function returns <c>ok</c>. On
587
failure, the function returns an opaque error, with the
588
exception of the <c>pending_process</c> error described
589
above. The opaque errors are to be translated into human
590
readable form by the <seealso marker="#format_error/1">format_error/1</seealso> function.</p>
591
<p>For more control over the error handling, again use the
592
<seealso marker="#try_load/3">try_load/3</seealso>
593
interface instead.</p>
594
<p>The function throws a <c>badarg</c> exception if the
595
parameters are not given as described above. </p>
599
<name>reload_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
600
<fsummary>Replace a driver</fsummary>
602
<v>Path = Name = string() | atom()</v>
603
<v>ErrorDesc = pending_process | OpaqueError</v>
604
<v>OpaqueError = term()</v>
607
<p>Works exactly as <seealso marker="#reload/2">reload/2</seealso>, but for drivers
608
loaded with the <seealso marker="#load_driver/2">load_driver/2</seealso> interface. </p>
609
<p>As this interface implies that ports are being killed when
610
the last user disappears, the function wont hang waiting for
611
ports to get closed.</p>
612
<p>For further details, see the <seealso marker="#scenarios">scenarios</seealso> in the module
613
description and refer to the <seealso marker="#reload/2">reload/2</seealso> function description.</p>
614
<p>The function throws a <c>badarg</c> exception if the
615
parameters are not given as described above. </p>
619
<name>try_load(Path, Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc}</name>
620
<fsummary>Load a driver</fsummary>
622
<v>Path = Name = string() | atom()</v>
623
<v>OptionList = [ Option ]</v>
624
<v>Option = {driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption}</v>
625
<v>DriverOptionList = [ DriverOption ]</v>
626
<v>DriverOption = kill_ports</v>
627
<v>MonitorOption = pending_driver | pending</v>
628
<v>ReloadOption = pending_driver | pending</v>
629
<v>Status = loaded | already_loaded | PendingStatus </v>
630
<v>PendingStatus = pending_driver | pending_process</v>
632
<v>ErrorDesc = ErrorAtom | OpaqueError</v>
633
<v>ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process</v>
636
<p>This function provides more control than the
637
<c>load/2</c>/<c>reload/2</c> and
638
<c>load_driver/2</c>/<c>reload_driver/2</c> interfaces. It
639
will never wait for completion of other operations related
640
to the driver, but immediately return the status of the
641
driver as either:</p>
643
<tag><em>{ok, loaded}</em></tag>
645
<p>The driver was actually loaded and is immediately
648
<tag><em>{ok, already_loaded}</em></tag>
650
<p>The driver was already loaded by another process
651
and/or is in use by a living port. The load by you is
652
registered and a corresponding <c>try_unload</c> is
653
expected sometime in the future.</p>
655
<tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, ref()}</em></tag>
657
<p>The load request is registered, but the loading is
658
delayed due to the fact that an earlier instance of the
659
driver is still waiting to get unloaded (there are open
660
ports using it). Still, unload is expected when you are
661
done with the driver. This return value will
662
<em>mostly</em> happen when the
663
<c>{reload,pending_driver}</c> or
664
<c>{reload,pending}</c> options are used, but
665
<em>can</em> happen when another <seealso marker="#users">user</seealso> is unloading a driver in
666
parallel and the <c>kill_ports</c> driver option is
667
set. In other words, this return value will always need
670
<tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, ref()}</em></tag>
672
<p>The load request is registered, but the loading is
673
delayed due to the fact that an earlier instance of the
674
driver is still waiting to get unloaded by another
675
<seealso marker="#users">user</seealso> (not only by a
676
port, in which case <c>{ok,pending_driver}</c> would
677
have been returned). Still, unload is expected when you
678
are done with the driver. This return value will
679
<em>only</em> happen when the <c>{reload,pending}</c>
683
<p>When the function returns <c>{ok, pending_driver}</c> or
684
<c>{ok, pending_process}</c>, one might want to get information
685
about when the driver is <em>actually</em> loaded. This can
686
be achieved by using the <c>{monitor, PendingOption}</c> option.</p>
687
<p>When monitoring is requested, and a corresponding <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would be
688
returned, the function will instead return a tuple <c>{ok, PendingStatus, ref()}</c> and the process will, at a later
689
time when the driver actually gets loaded, get a monitor
690
message. The monitor message one can expect is described in
691
the <seealso marker="#monitor/2">monitor/2</seealso>
692
function description. </p>
694
<p>Note that in case of loading, monitoring can
695
<em>not</em> only get triggered by using the <c>{reload, ReloadOption}</c> option, but also in special cases where
696
the load-error is transient, why <c>{monitor, pending_driver}</c> should be used under basically
697
<em>all</em> real world circumstances!</p>
699
<p>The function accepts the following parameters:</p>
701
<tag><em>Path</em></tag>
703
<p>The filesystem path to the directory where the driver
704
object file is situated. The filename of the object file
705
(minus extension) must correspond to the driver name
706
(used in the name parameter) and the driver must
707
identify itself with the very same name. The
708
<c>Path</c> might be provided as an <em>io_list</em>,
709
meaning it can be a list of other io_lists, characters
710
(eight bit integers) or binaries, all to be flattened
711
into a sequence of characters.</p>
712
<p>The (possibly flattened) <c>Path</c> parameter must be
713
consistent throughout the system, a driver should, by
714
all <seealso marker="#users">users</seealso>, be loaded
715
using the same <em>literal</em><c>Path</c>. The
716
exception is when <em>reloading</em> is requested, in
717
which case the <c>Path</c> may be specified
718
differently. Note that all <seealso marker="#users">users</seealso> trying to load the
719
driver at a later time will need to use the <em>new</em><c>Path</c> if the <c>Path</c> is changed using a
720
<c>reload</c> option. This is yet another reason
721
to have <em>only one loader</em> of a driver one wants to
722
upgrade in a running system! </p>
724
<tag><em>Name</em></tag>
726
<p>The name parameter is the name of the driver to be used
727
in subsequent calls to <seealso marker="erlang#open_port/2">open_port</seealso>. The
728
name can be specified either as an <c>io_list()</c> or
729
as an <c>atom()</c>. The name given when loading is used
730
to find the actual object file (with the
731
help of the <c>Path</c> and the system implied
732
extension suffix, i.e. <c>.so</c>). The name by which
733
the driver identifies itself must also be consistent
734
with this <c>Name</c> parameter, much as a beam-file's
735
module name much correspond to it's filename.</p>
737
<tag><em>OptionList</em></tag>
739
<p>A number of options can be specified to control the
740
loading operation. The options are given as a list of
741
two-tuples, the tuples having the following values and
744
<tag><em>{driver_options, DriverOptionsList}</em></tag>
746
<p>This option is to provide options that will change
747
it's general behavior and will "stick" to the driver
748
throughout it's lifespan.</p>
749
<p>The driver options for a given driver name need
750
always to be consistent, <em>even when the driver is reloaded</em>, meaning that they are as much a part
751
of the driver as the actual name.</p>
752
<p>Currently the only allowed driver option is
753
<c>kill_ports</c>, which means that all ports opened
754
towards the driver are killed with the exit-reason
755
<c>driver_unloaded</c> when no process any longer
756
has the driver loaded. This situation arises either
757
when the last <seealso marker="#users">user</seealso> calls <seealso marker="#try_unload/2">try_unload/2</seealso>, or
758
the last process having loaded the driver exits.</p>
760
<tag><em>{monitor, MonitorOption}</em></tag>
762
<p>A <c>MonitorOption</c> tells <c>try_load/3</c> to
763
trigger a driver monitor under certain
764
conditions. When the monitor is triggered, the
765
function will return a three-tuple <c>{ok, PendingStatus, ref()}</c>, where the <c>ref()</c> is
766
the monitor ref for the driver monitor.</p>
767
<p>Only one <c>MonitorOption</c> can be specified and
768
it is either the atom <c>pending</c>, which means
769
that a monitor should be created whenever a load
770
operation is delayed, and the atom
771
<c>pending_driver</c>, in which a monitor is
772
created whenever the operation is delayed due to
773
open ports towards an otherwise unused driver. The
774
<c>pending_driver</c> option is of little use, but
775
is present for completeness, it is very well defined
776
which reload-options might give rise to which
777
delays. It might, however, be a good idea to use the
778
same <c>MonitorOption</c> as the <c>ReloadOption</c>
780
<p>If reloading is not requested, it might still be
781
useful to specify the <c>monitor</c> option, as
782
forced unloads (<c>kill_ports</c> driver option or
783
the <c>kill_ports</c> option to <seealso marker="#try_unload/2">try_unload/2</seealso>) will
784
trigger a transient state where driver loading
785
cannot be performed until all closing ports are
786
actually closed. So, as <c>try_unload</c> can, in
787
almost all situations, return <c>{ok, pending_driver}</c>, one should always specify at least
788
<c>{monitor, pending_driver}</c> in production
789
code (see the monitor discussion above). </p>
791
<tag><em>{reload,RealoadOption}</em></tag>
793
<p>This option is used when one wants to
794
<em>reload</em> a driver from disk, most often in a
795
code upgrade scenario. Having a <c>reload</c> option
796
also implies that the <c>Path</c> parameter need
797
<em>not</em> be consistent with earlier loads of
799
<p>To reload a driver, the process needs to have previously
800
loaded the driver, i.e there has to be an active <seealso marker="#users">user</seealso> of the driver in the process. </p>
801
<p>The <c>reload</c> option can be either the atom
802
<c>pending</c>, in which reloading is requested for
803
any driver and will be effectuated when <em>all</em>
804
ports opened against the driver are closed. The
805
replacement of the driver will in this case take
806
place regardless of if there are still
807
pending <seealso marker="#users">users</seealso>
808
having the driver loaded!
809
The option also triggers port-killing (if the
810
<c>kill_ports</c> driver option is used) even though
811
there are pending users, making it usable for forced
812
driver replacement, but laying a lot of
813
responsibility on the driver <seealso marker="#users">users</seealso>. The pending option is
814
seldom used as one does not want other <seealso marker="#users">users</seealso> to have loaded the
815
driver when code change is underway. </p>
816
<p>The more useful option is <c>pending_driver</c>,
817
which means that reloading will be queued if the
818
driver is <em>not</em> loaded by any other <seealso marker="#users">users</seealso>, but the driver has
819
opened ports, in which case <c>{ok, pending_driver}</c> will be returned (a
820
<c>monitor</c> option is of course recommended).</p>
821
<p>If the driver is unloaded (not present in the
822
system), the error code
823
<c>not_loaded</c> will be returned. The
824
<c>reload</c> option is intended for when the user
825
has already loaded the driver in advance.</p>
830
<p>The function might return numerous errors, of which some
831
only can be returned given a certain combination of options.</p>
832
<p>A number of errors are opaque and can only be interpreted by
833
passing them to the <seealso marker="#format_error/1">format_error/1</seealso> function,
834
but some can be interpreted directly:</p>
836
<tag><em>{error,linked_in_driver}</em></tag>
838
<p>The driver with the specified name is an erlang
839
statically linked in driver, which cannot be manipulated
842
<tag><em>{error,inconsistent}</em></tag>
844
<p>The driver has already been loaded with either other
845
<c>DriverOptions</c> or a different <em>literal</em><c>Path</c> argument.</p>
846
<p>This can happen even if a <c>reload</c> option is given,
847
if the <c>DriverOptions</c> differ from the current.</p>
849
<tag><em>{error, permanent}</em></tag>
851
<p>The driver has requested itself to be permanent, making
852
it behave like an erlang linked in driver and it can no
853
longer be manipulated with this API.</p>
855
<tag><em>{error, pending_process}</em></tag>
857
<p>The driver is loaded by other <seealso marker="#users">users</seealso> when the <c>{reload, pending_driver}</c> option was given.</p>
859
<tag><em>{error, pending_reload}</em></tag>
861
<p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, ReloadOption}</c> option was given.</p>
863
<tag><em>{error, not_loaded_by_this_process}</em></tag>
865
<p>Appears when the <c>reload</c> option is given. The
866
driver <c>Name</c> is present in the system, but there is no
867
<seealso marker="#users">user</seealso> of it in this
870
<tag><em>{error, not_loaded}</em></tag>
872
<p>Appears when the <c>reload</c> option is given. The
873
driver <c>Name</c> is not in the system. Only drivers
874
loaded by this process can be reloaded.</p>
877
<p>All other error codes are to be translated by the <seealso marker="#format_error/1">format_error/1</seealso>
878
function. Note that calls to <c>format_error</c> should be
879
performed from the same running instance of the erlang
880
virtual machine as the error was detected in, due to system
881
dependent behavior concerning error values.</p>
882
<p>If the arguments or options are malformed, the function will
883
throw a <c>badarg</c> exception.</p>
887
<name>try_unload(Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom}</name>
888
<fsummary>Unload a driver</fsummary>
890
<v>Name = string() | atom()</v>
891
<v>OptionList = [ Option ]</v>
892
<v>Option = {monitor, MonitorOption} | kill_ports</v>
893
<v>MonitorOption = pending_driver | pending</v>
894
<v>Status = unloaded | PendingStatus </v>
895
<v>PendingStatus = pending_driver | pending_process</v>
897
<v>ErrorAtom = linked_in_driver | not_loaded | not_loaded_by_this_process | permanent</v>
900
<p>This is the low level function to unload (or decrement
901
reference counts of) a driver. It can be used to force port
902
killing, in much the same way as the driver option
903
<c>kill_ports</c> implicitly does, and it can trigger a
904
monitor either due to other <seealso marker="#users">users</seealso> still having the driver
905
loaded or that there are open ports using the driver.</p>
906
<p>Unloading can be described as the process of telling the
907
emulator that this particular part of the code in this
908
particular process (i.e. this <seealso marker="#users">user</seealso>) no longer needs the
909
driver. That can, if there are no other users, trigger
910
actual unloading of the driver, in which case the driver
911
name disappears from the system and (if possible) the memory
912
occupied by the driver executable code is reclaimed. If the
913
driver has the <c>kill_ports</c> option set, or if
914
<c>kill_ports</c> was specified as an option to this
915
function, all pending ports using this driver will get
916
killed when unloading is done by the last <seealso marker="#users">user</seealso>. If no port-killing is
917
involved and there are open ports, the actual unloading
918
is delayed until there are no more open ports using the
919
driver. If, in this case, another <seealso marker="#users">user</seealso> (or even this user) loads the
920
driver again before the driver is actually unloaded, the
921
unloading will never take place.</p>
922
<p>To allow the <seealso marker="#users">user</seealso> that
923
<em>requests unloading</em> to wait for <em>actual unloading</em> to
924
take place, <c>monitor</c> triggers can be specified in much
925
the same way as when loading. As <seealso marker="#users">users</seealso> of this function however
926
seldom are interested in more than decrementing the
927
reference counts, monitoring is more seldom needed. If the
928
<c>kill_ports</c> option is used however, monitor trigging is
929
crucial, as the ports are not guaranteed to have been killed
930
until the driver is unloaded, why a monitor should be
931
triggered for at least the <c>pending_driver</c> case.</p>
932
<p>The possible monitor messages that can be expected are the
933
same as when using the <c>unloaded</c> option to the
934
<seealso marker="#monitor/2">monitor/2</seealso> function.</p>
935
<p>The function will return one of the following statuses upon
938
<tag><em>{ok, unloaded}</em></tag>
940
<p>The driver was immediately unloaded, meaning that the
941
driver name is now free to use by other drivers and, if
942
the underlying OS permits it, the memory occupied by the
943
driver object code is now reclaimed.</p>
944
<p>The driver can only be unloaded when there are no open
945
ports using it and there are no more <seealso marker="#users">users</seealso> requiring it to be
948
<tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, ref()}</em></tag>
950
<p>This return value indicates that this call removed the
951
last <seealso marker="#users">user</seealso> from the
952
driver, but there are still open ports using it.
953
When all ports are closed and no new <seealso marker="#users">users</seealso> have arrived, the driver
954
will actually be reloaded and the name and memory
956
<p>This return value is valid even when the option
957
<c>kill_ports</c> was used, as killing ports may not be
958
a process that completes immediately. The condition is,
959
in that case, however transient. Monitors are as always
960
useful to detect when the driver is really unloaded.</p>
962
<tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, ref()}</em></tag>
964
<p>The unload request is registered, but there are still
965
other <seealso marker="#users">users</seealso> holding
966
the driver. Note that the term <c>pending_process</c>
967
might refer to the running process, there might be more
968
than one <seealso marker="#users">user</seealso> in the
970
<p>This is a normal, healthy return value if the call was
971
just placed to inform the emulator that you have no
972
further use of the driver. It is actually the most
973
common return value in the most common <seealso marker="#scenarios">scenario</seealso>
974
described in the introduction.</p>
977
<p>The function accepts the following parameters:</p>
979
<tag><em>Name</em></tag>
981
<p>The name parameter is the name of the driver to be
982
unloaded. The name can be specified either as an
983
<c>io_list()</c> or as an <c>atom()</c>. </p>
985
<tag><em>OptionList</em></tag>
987
<p>The <c>OptionList</c> argument can be used to specify
988
certain behavior regarding ports as well as triggering
989
monitors under certain conditions:</p>
991
<tag><em>kill_ports</em></tag>
993
<p>Force killing of all ports opened using this driver,
994
with the exit reason <c>driver_unloaded</c>, if you are
995
the <em>last</em><seealso marker="#users">user</seealso> of the driver.</p>
996
<p>If there are other <seealso marker="#users">users</seealso> having the driver
997
loaded, this option will have no effect.</p>
998
<p>If one wants the consistent behavior of killing ports
999
when the last <seealso marker="#users">user</seealso>
1000
unloads, one should use the driver option
1001
<c>kill_ports</c> when loading the driver instead.</p>
1003
<tag><em>{monitor, MonitorOption}</em></tag>
1005
<p>This option creates a driver monitor if the condition
1006
given in <c>MonitorOptions</c> is true. The valid
1009
<tag><em>pending_driver</em></tag>
1011
<p>Create a driver monitor if the return value is to
1012
be <c>{ok, pending_driver}</c>.</p>
1014
<tag><em>pending</em></tag>
1016
<p>Create a monitor if the return value will be either
1017
<c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>.</p>
1020
<p>The <c>pending_driver</c><c>MonitorOption</c> is by far
1021
the most useful and it has to be used to ensure that the
1022
driver has really been unloaded and the ports closed
1023
whenever the <c>kill_ports</c> option is used or the
1024
driver may have been loaded with the <c>kill_ports</c>
1026
<p>By using the monitor-triggers in the call to
1027
<c>try_unload</c> one can be sure that the monitor is
1028
actually added before the unloading is executed, meaning
1029
that the monitor will always get properly triggered,
1030
which would not be the case if one called
1031
<c>erl_ddll:monitor/2</c> separately.</p>
1036
<p>The function may return several error conditions, of which
1037
all are well specified (no opaque values):</p>
1039
<tag><em>{error, linked_in_driver}</em></tag>
1041
<p>You were trying to unload an erlang statically linked in
1042
driver, which cannot be manipulated with this interface
1043
(and cannot be unloaded at all).</p>
1045
<tag><em>{error, not_loaded}</em></tag>
1047
<p>The driver <c>Name</c> is not present in the system.</p>
1049
<tag><em>{error, not_loaded_by_this_process}</em></tag>
1051
<p>The driver <c>Name</c> is present in the system, but
1052
there is no <seealso marker="#users">user</seealso> of
1053
it in this process. </p>
1054
<p>As a special case, drivers can be unloaded from
1055
processes that has done no corresponding call to
1056
<c>try_load/3</c> if, and only if, there are <em>no users of the driver at all</em>, which may happen if the
1057
process containing the last user dies.</p>
1059
<tag><em>{error, permanent}</em></tag>
1061
<p>The driver has made itself permanent, in which case it
1062
can no longer be manipulated by this interface (much
1063
like a statically linked in driver).</p>
1066
<p>The function throws a <c>badarg</c> exception if the
1067
parameters are not given as described above. </p>
1071
<name>unload(Name) -> ok | {error, ErrorDesc}</name>
1072
<fsummary>Unload a driver</fsummary>
1074
<v>Name = string() | atom()</v>
1075
<v>ErrorDesc = term()</v>
1078
<p>Unloads, or at least dereferences the driver named
1079
<c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, and there
1080
are no more open ports using the driver, the driver will
1081
actually get unloaded. In all other cases, actual unloading
1082
will be delayed until all ports are closed and there are no
1083
remaining <seealso marker="#users">users</seealso>.</p>
1084
<p>If there are other <seealso marker="#users">users</seealso> of the driver, the reference
1085
counts of the driver is merely decreased, so that the caller
1086
is no longer considered a user of the driver. For usage
1087
scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning
1088
of this document. </p>
1089
<p>The <c>ErrorDesc</c> returned is an opaque value to be
1090
passed further on to the <seealso marker="#format_error/1">format_error/1</seealso>
1091
function. For more control over the operation, use the
1092
<seealso marker="#try_unload/2">try_unload/2</seealso>
1094
<p>The function throws a <c>badarg</c> exception if the
1095
parameters are not given as described above. </p>
1099
<name>unload_driver(Name) -> ok | {error, ErrorDesc}</name>
1100
<fsummary>Unload a driver</fsummary>
1102
<v>Name = string() | atom()</v>
1103
<v>ErrorDesc = term()</v>
1106
<p>Unloads, or at least dereferences the driver named
1107
<c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, all
1108
remaining open ports using the driver will get killed with
1109
the reason <c>driver_unloaded</c> and the driver will
1110
eventually get unloaded.</p>
1111
<p>If there are other <seealso marker="#users">users</seealso>
1112
of the driver, the reference counts of the driver is merely
1113
decreased, so that the caller is no longer considered a
1114
<seealso marker="#users">user</seealso>. For
1115
usage scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning
1116
of this document.</p>
1117
<p>The <c>ErrorDesc</c> returned is an opaque value to be
1118
passed further on to the <seealso marker="#format_error/1">format_error/1</seealso>
1119
function. For more control over the operation, use the
1120
<seealso marker="#try_unload/2">try_unload/2</seealso>
1122
<p>The function throws a <c>badarg</c> exception if the
1123
parameters are not given as described above. </p>
1127
<name>loaded_drivers() -> {ok, Drivers}</name>
1128
<fsummary>List loaded drivers</fsummary>
1130
<v>Drivers = [Driver()]</v>
1131
<v>Driver = string()</v>
1134
<p>Returns a list of all the available drivers, both
1135
(statically) linked-in and dynamically loaded ones.</p>
1136
<p>The driver names are returned as a list of strings rather
1137
than a list of atoms for historical reasons.</p>
1138
<p>More information about drivers can be obtained using one of
1139
the <seealso marker="#info/0">info</seealso> functions.</p>
1143
<name>format_error(ErrorDesc) -> string()</name>
1144
<fsummary>Format an error descriptor</fsummary>
1146
<v>ErrorDesc -- see below</v>
1149
<p>Takes an <c>ErrorDesc</c> returned by load, unload or
1150
reload functions and returns a string which
1151
describes the error or warning.</p>
1153
<p>Due to peculiarities in the dynamic loading interfaces on
1154
different platform, the returned string is only guaranteed
1155
to describe the correct error <em>if format_error/1 is called in the same instance of the erlang virtual machine as the error appeared in</em> (meaning the same operating
1156
system process)!</p>
1163
<title>SEE ALSO</title>
1164
<p>erl_driver(4), driver_entry(4)</p>
added
removed
lib/kernel/doc/src/erl_ddll.xml
