1erl_ddll(3)                Erlang Module Definition                erl_ddll(3)
2
3
4

NAME

6       erl_ddll - Dynamic driver loader and linker.
7

DESCRIPTION

9       This  module  provides  an  interface  for loading and unloading Erlang
10       linked-in drivers in runtime.
11
12   Note:
13       This is a large reference document. For casual use of this module,  and
14       for  most real world applications, the descriptions of functions load/2
15       and unload/1 are enough to getting started.
16
17
18       The driver is to be provided as a  dynamically  linked  library  in  an
19       object code format specific for the platform in use, that is, .so files
20       on most Unix systems and .ddl files on  Windows.  An  Erlang  linked-in
21       driver must provide specific interfaces to the emulator, so this module
22       is not designed for  loading  arbitrary  dynamic  libraries.  For  more
23       information about Erlang drivers, see erts:erl_driver .
24
25       When describing a set of functions (that is, a module, a part of a mod‐
26       ule, or an application), executing in a process and wanting  to  use  a
27       ddll-driver,  we use the term user. A process can have many users (dif‐
28       ferent modules needing the same driver) and many processes running  the
29       same code, making up many users of a driver.
30
31       In  the  basic  scenario, each user loads the driver before starting to
32       use it and unloads the driver when done. The reference  counting  keeps
33       track  of  processes  and the number of loads by each process. This way
34       the driver is only unloaded when no one wants it (it has no user).  The
35       driver  also  keeps  track of ports that are opened to it. This enables
36       delay of unloading until all ports are closed, or killing of all  ports
37       that use the driver when it is unloaded.
38
39       The  interface  supports  two basic scenarios of loading and unloading.
40       Each scenario can also have the option of either killing ports when the
41       driver  is unloading, or waiting for the ports to close themselves. The
42       scenarios are as follows:
43
44         Load and Unload on a "When Needed Basis":
45           This (most common) scenario simply supports that each user  of  the
46           driver  loads  it when needed and unloads it when no longer needed.
47           The driver is always reference counted and as  long  as  a  process
48           keeping  the driver loaded is still alive, the driver is present in
49           the system.
50
51           Each user of the driver use literally the  same  pathname  for  the
52           driver when demanding load, but the users are not concerned with if
53           the driver is already loaded from the file system or if the  object
54           code must be loaded from file system.
55
56           The following two pairs of functions support this scenario:
57
58           load/2 and unload/1:
59             When using the load/unload interfaces, the driver is not unloaded
60             until the last port using the driver is closed. Function unload/1
61             can  return  immediately,  as the users have no interrest in when
62             the unloading occurs. The driver is unloaded when no one needs it
63             any longer.
64
65             If  a  process  having  the  driver  loaded dies, it has the same
66             effect as if unloading is done.
67
68             When loading, function load/2 returns ok when any instance of the
69             driver  is  present. Thus, if a driver is waiting to get unloaded
70             (because of open ports), it simply changes  state  to  no  longer
71             need unloading.
72
73           load_driver/2 and unload_driver/1:
74             These interfaces are intended to be used when it is considered an
75             error that ports are open to a driver that no  user  has  loaded.
76             The   ports  that  are  still  open  when  the  last  user  calls
77             unload_driver/1 or when the last process having the driver loaded
78             dies, are killed with reason driver_unloaded.
79
80             The  function  names  load_driver  and unload_driver are kept for
81             backward compatibility.
82
83         Loading and Reloading for Code Replacement:
84           This scenario can occur if the driver code needs replacement during
85           operation of the Erlang emulator. Implementing driver code replace‐
86           ment is a little more tedious than Beam code  replacement,  as  one
87           driver  cannot be loaded as both "old" and "new" code. All users of
88           a driver must have it closed (no open ports) before  the  old  code
89           can be unloaded and the new code can be loaded.
90
91           The unloading/loading is done as one atomic operation, blocking all
92           processes in the system from using the driver in question while  in
93           progress.
94
95           The  preferred way to do driver code replacement is to let one sin‐
96           gle process keep track of the driver. When the process starts,  the
97           driver  is  loaded.  When  replacement  is  required, the driver is
98           reloaded. Unload is probably never done, or done when  the  process
99           exits. If more than one user has a driver loaded when code replace‐
100           ment is demanded, the  replacement  cannot  occur  until  the  last
101           "other" user has unloaded the driver.
102
103           Demanding  reload when a reload is already in progress is always an
104           error. Using the high-level functions,  it  is  also  an  error  to
105           demand reloading when more than one user has the driver loaded.
106
107           To simplify driver replacement, avoid designing your system so that
108           more than one user has the driver loaded.
109
110           The two functions for reloading drivers are  to  be  used  together
111           with  corresponding  load  functions  to  support the two different
112           behaviors concerning open ports:
113
114           load/2 and reload/2:
115             This pair of functions is used when reloading is to be done after
116             the last open port to the driver is closed.
117
118             As  reload/2  waits  for  the  reloading  to occur, a misbehaving
119             process keeping open ports to the driver (or keeping  the  driver
120             loaded)  can cause infinite waiting for reload. Time-outs must be
121             provided outside of the process demanding the reload or by  using
122             the  low-level  interface  try_load/3  in combination with driver
123             monitors.
124
125           load_driver/2 and reload_driver/2:
126             This pair of functions are used when open ports to the driver are
127             to  be killed with reason driver_unloaded to allow for new driver
128             code to get loaded.
129
130             However, if  another  process  has  the  driver  loaded,  calling
131             reload_driver  returns error code pending_process. As stated ear‐
132             lier, the recommended design is to not allow other users than the
133             "driver reloader" to demand loading of the driver in question.
134

DATA TYPES

136       driver() = iolist() | atom()
137
138       path() = string() | atom()
139

EXPORTS

141       demonitor(MonitorRef) -> ok
142
143              Types:
144
145                 MonitorRef = reference()
146
147              Removes  a driver monitor in much the same way as erlang:demoni‐
148              tor/1 in ERTS does with process monitors. For details about  how
149              to  create  driver  monitors,  see  monitor/2,  try_load/3,  and
150              try_unload/2.
151
152              The function throws a badarg exception if the parameter is not a
153              reference().
154
155       format_error(ErrorDesc) -> string()
156
157              Types:
158
159                 ErrorDesc = term()
160
161              Takes an ErrorDesc returned by load, unload, or reload functions
162              and returns a string that describes the error or warning.
163
164          Note:
165              Because of peculiarities in the dynamic  loading  interfaces  on
166              different  platforms,  the returned string is only guaranteed to
167              describe the correct error if format_error/1 is  called  in  the
168              same  instance  of  the  Erlang  virtual  machine  as  the error
169              appeared in (meaning the same operating system process).
170
171
172       info() -> AllInfoList
173
174              Types:
175
176                 AllInfoList = [DriverInfo]
177                 DriverInfo = {DriverName, InfoList}
178                 DriverName = string()
179                 InfoList = [InfoItem]
180                 InfoItem = {Tag :: atom(), Value :: term()}
181
182              Returns a list of tuples {DriverName, InfoList}, where  InfoList
183              is the result of calling info/1 for that DriverName. Only dynam‐
184              ically linked-in drivers are included in the list.
185
186       info(Name) -> InfoList
187
188              Types:
189
190                 Name = driver()
191                 InfoList = [InfoItem, ...]
192                 InfoItem = {Tag :: atom(), Value :: term()}
193
194              Returns a list of tuples {Tag, Value}, where Tag is the informa‐
195              tion  item  and  Value is the result of calling info/2 with this
196              driver name and this tag. The result is a tuple list  containing
197              all information available about a driver.
198
199              The following tags appears in the list:
200
201                * processes
202
203                * driver_options
204
205                * port_count
206
207                * linked_in_driver
208
209                * permanent
210
211                * awaiting_load
212
213                * awaiting_unload
214
215              For a detailed description of each value, see info/2.
216
217              The  function  throws  a  badarg  exception if the driver is not
218              present in the system.
219
220       info(Name, Tag) -> Value
221
222              Types:
223
224                 Name = driver()
225                 Tag =
226                     processes    |    driver_options    |    port_count     |
227                 linked_in_driver |
228                     permanent | awaiting_load | awaiting_unload
229                 Value = term()
230
231              Returns  specific  information  about  one  aspect  of a driver.
232              Parameter Tag specifies which aspect to get  information  about.
233              The return Value differs between different tags:
234
235                processes:
236                  Returns all processes containing users of the specific driv‐
237                  ers as a list of tuples {pid(),integer() >= 0}, where  inte‐
238                  ger() denotes the number of users in process pid().
239
240                driver_options:
241                  Returns  a list of the driver options provided when loading,
242                  and any options set by the driver during initialization. The
243                  only valid option is kill_ports.
244
245                port_count:
246                  Returns  the  number  of ports (an integer() >= 0) using the
247                  driver.
248
249                linked_in_driver:
250                  Returns a boolean(), which is true if the driver is a stati‐
251                  cally linked-in one, otherwise false.
252
253                permanent:
254                  Returns  a  boolean(),  which is true if the driver has made
255                  itself permanent (and is not a statically linked-in driver),
256                  otherwise false.
257
258                awaiting_load:
259                  Returns  a list of all processes having monitors for loading
260                  active. Each process is returned as {pid(),integer() >=  0},
261                  where  integer()  is  the number of monitors held by process
262                  pid().
263
264                awaiting_unload:
265                  Returns a list of all processes having monitors for  unload‐
266                  ing  active. Each process is returned as {pid(),integer() >=
267                  0}, where integer()  is  the  number  of  monitors  held  by
268                  process pid().
269
270              If  option linked_in_driver or permanent returns true, all other
271              options return linked_in_driver or permanent, respectively.
272
273              The function throws a badarg exception  if  the  driver  is  not
274              present in the system or if the tag is not supported.
275
276       load(Path, Name) -> ok | {error, ErrorDesc}
277
278              Types:
279
280                 Path = path()
281                 Name = driver()
282                 ErrorDesc = term()
283
284              Loads  and links the dynamic driver Name. Path is a file path to
285              the directory containing the driver. Name  must  be  a  sharable
286              object/dynamic  library. Two drivers with different Path parame‐
287              ters cannot be loaded under the same name. Name is a  string  or
288              atom containing at least one character.
289
290              The  Name  specified  is  to  correspond  to the filename of the
291              dynamically loadable object file residing in the directory spec‐
292              ified  as  Path,  but  without the extension (that is, .so). The
293              driver name provided in the driver initialization  routine  must
294              correspond  with  the  filename,  in much the same way as Erlang
295              module names correspond to the names of the .beam files.
296
297              If the driver was previously  unloaded,  but  is  still  present
298              because  of open ports to it, a call to load/2 stops the unload‐
299              ing and keeps the driver (as long as Path is the same),  and  ok
300              is  returned. If you really want the object code to be reloaded,
301              use reload/2 or the low-level interface try_load/3 instead.  See
302              also  the description of different scenarios for loading/unload‐
303              ing in the introduction.
304
305              If more than one process tries to load an already loaded  driver
306              with the same Path, or if the same process tries to load it many
307              times, the function returns ok. The emulator keeps track of  the
308              load/2  calls,  so that a corresponding number of unload/2 calls
309              must be done from  the  same  process  before  the  driver  gets
310              unloaded.  It  is  therefore  safe  for an application to load a
311              driver that is shared between  processes  or  applications  when
312              needed.  It  can  safely be unloaded without causing trouble for
313              other parts of the system.
314
315              It is not allowed to load multiple drivers with  the  same  name
316              but with different Path parameters.
317
318          Note:
319              Path  is  interpreted literally, so that all loaders of the same
320              driver must specify the same literal Path string, although  dif‐
321              ferent paths can point out the same directory in the file system
322              (because of use of relative paths and links).
323
324
325              On success, the function returns  ok.  On  failure,  the  return
326              value is {error,ErrorDesc}, where ErrorDesc is an opaque term to
327              be  translated  into  human  readable  form  by  function   for‐
328              mat_error/1.
329
330              For  more  control  over  the error handling, use the try_load/3
331              interface instead.
332
333              The function throws a badarg exception if the parameters are not
334              specified as described here.
335
336       load_driver(Path, Name) -> ok | {error, ErrorDesc}
337
338              Types:
339
340                 Path = path()
341                 Name = driver()
342                 ErrorDesc = term()
343
344              Works  essentially  as  load/2,  but loads the driver with other
345              options. All ports using  the  driver  are  killed  with  reason
346              driver_unloaded when the driver is to be unloaded.
347
348              The  number  of  loads and unloads by different users influences
349              the loading and unloading of a driver  file.  The  port  killing
350              therefore  only occurs when the last user unloads the driver, or
351              when the last process having loaded the driver exits.
352
353              This interface (or at least the name of the functions)  is  kept
354              for    backward    compatibility.    Using    try_load/3    with
355              {driver_options,[kill_ports]} in the option list gives the  same
356              effect regarding the port killing.
357
358              The function throws a badarg exception if the parameters are not
359              specified as described here.
360
361       loaded_drivers() -> {ok, Drivers}
362
363              Types:
364
365                 Drivers = [Driver]
366                 Driver = string()
367
368              Returns a list of all the available drivers,  both  (statically)
369              linked-in and dynamically loaded ones.
370
371              The driver names are returned as a list of strings rather than a
372              list of atoms for historical reasons.
373
374              For more information about drivers, see info.
375
376       monitor(Tag, Item) -> MonitorRef
377
378              Types:
379
380                 Tag = driver
381                 Item = {Name, When}
382                 Name = driver()
383                 When = loaded | unloaded | unloaded_only
384                 MonitorRef = reference()
385
386              Creates a driver monitor and works in many ways as  erlang:moni‐
387              tor/2  in ERTS, does for processes. When a driver changes state,
388              the monitor results in a monitor message that  is  sent  to  the
389              calling   process.  MonitorRef  returned  by  this  function  is
390              included in the message sent.
391
392              As with process monitors, each driver monitor set only generates
393              one single message. The monitor is "destroyed" after the message
394              is sent, so it is then not needed to call demonitor/1.
395
396              MonitorRef can also be used in subsequent calls  to  demonitor/1
397              to remove a monitor.
398
399              The function accepts the following parameters:
400
401                Tag:
402                  The  monitor tag is always driver, as this function can only
403                  be used to create driver monitors.  In  the  future,  driver
404                  monitors  will be integrated with process monitors, why this
405                  parameter has to be specified for consistence.
406
407                Item:
408                  Parameter Item specifies which driver to monitor (the driver
409                  name)  and which state change to monitor. The parameter is a
410                  tuple of arity two whose first element is  the  driver  name
411                  and second element is one of the following:
412
413                  loaded:
414                    Notifies when the driver is reloaded (or loaded if loading
415                    is underway). It only makes sense to monitor drivers  that
416                    are  in  the process of being loaded or reloaded. A future
417                    driver name for loading cannot  be  monitored.  That  only
418                    results in a DOWN message sent immediately. Monitoring for
419                    loading is therefore most useful when triggered  by  func‐
420                    tion  try_load/3, where the monitor is created because the
421                    driver is in such a pending state.
422
423                    Setting a driver monitor for loading eventually  leads  to
424                    one of the following messages being sent:
425
426                    {'UP', reference(), driver, Name, loaded}:
427                      This message is sent either immediately if the driver is
428                      already loaded and no  reloading  is  pending,  or  when
429                      reloading is executed if reloading is pending.
430
431                      The  user  is  expected to know if reloading is demanded
432                      before creating a monitor for loading.
433
434                    {'UP', reference(), driver, Name, permanent}:
435                      This message is sent if reloading was expected, but  the
436                      (old)  driver made itself permanent before reloading. It
437                      is also sent if the driver was permanent  or  statically
438                      linked-in when trying to create the monitor.
439
440                    {'DOWN', reference(), driver, Name, load_cancelled}:
441                      This  message arrives if reloading was underway, but the
442                      requesting  user  cancelled  it  by  dying  or   calling
443                      try_unload/2  (or unload/1/unload_driver/1) again before
444                      it was reloaded.
445
446                    {'DOWN', reference(), driver, Name,  {load_failure,  Fail‐
447                    ure}}:
448                      This  message  arrives if reloading was underway but the
449                      loading for some reason failed. The Failure term is  one
450                      of  the errors that can be returned from try_load/3. The
451                      error term can be passed to format_error/1 for  transla‐
452                      tion  into human readable form. Notice that the transla‐
453                      tion must be done in the  same  running  Erlang  virtual
454                      machine as the error was detected in.
455
456                  unloaded:
457                    Monitors  when  a  driver gets unloaded. If one monitors a
458                    driver that is not present in the system, one  immediately
459                    gets  notified  that  the driver got unloaded. There is no
460                    guarantee that the driver was ever loaded.
461
462                    A driver monitor for unload eventually results in  one  of
463                    the following messages being sent:
464
465                    {'DOWN', reference(), driver, Name, unloaded}:
466                      The  monitored  driver  instance is now unloaded. As the
467                      unload can be a result of a reload/2 request, the driver
468                      can  once  again  have  been  loaded  when  this message
469                      arrives.
470
471                    {'UP', reference(), driver, Name, unload_cancelled}:
472                      This message is sent  if  unloading  was  expected,  but
473                      while  the  driver  was  waiting  for  all  ports to get
474                      closed, a new user  of  the  driver  appeared,  and  the
475                      unloading was cancelled.
476
477                      This   message   appears  if  {ok,  pending_driver}  was
478                      returned from try_unload/2 for  the  last  user  of  the
479                      driver, and then {ok, already_loaded} is returned from a
480                      call to try_load/3.
481
482                      If one really wants to  monitor  when  the  driver  gets
483                      unloaded,  this message distorts the picture, because no
484                      unloading was done. Option unloaded_only creates a moni‐
485                      tor similar to an unloaded monitor, but never results in
486                      this message.
487
488                    {'UP', reference(), driver, Name, permanent}:
489                      This message is sent if unloading was expected, but  the
490                      driver  made  itself  permanent  before unloading. It is
491                      also sent if trying to monitor a permanent or statically
492                      linked-in driver.
493
494                  unloaded_only:
495                    A  monitor created as unloaded_only behaves exactly as one
496                    created as unloaded except that  the  {'UP',  reference(),
497                    driver, Name, unload_cancelled} message is never sent, but
498                    the monitor instead persists until the driver really  gets
499                    unloaded.
500
501              The function throws a badarg exception if the parameters are not
502              specified as described here.
503
504       reload(Path, Name) -> ok | {error, ErrorDesc}
505
506              Types:
507
508                 Path = path()
509                 Name = driver()
510                 ErrorDesc = pending_process | OpaqueError
511                 OpaqueError = term()
512
513              Reloads the driver named Name from  a  possibly  different  Path
514              than  previously  used. This function is used in the code change
515              scenario described in the introduction.
516
517              If there are other users of this driver,  the  function  returns
518              {error,  pending_process},  but if there are no other users, the
519              function call hangs until all open ports are closed.
520
521          Note:
522              Avoid mixing multiple users with driver reload requests.
523
524
525              To avoid hanging on open ports, use function try_load/3 instead.
526
527              The Name and Path parameters have exactly the  same  meaning  as
528              when calling the plain function load/2.
529
530              On  success,  the  function returns ok. On failure, the function
531              returns  an  opaque  error,  except  the  pending_process  error
532              described  earlier.  The opaque errors are to be translated into
533              human readable form by function format_error/1.
534
535              For more control over the error  handling,  use  the  try_load/3
536              interface instead.
537
538              The function throws a badarg exception if the parameters are not
539              specified as described here.
540
541       reload_driver(Path, Name) -> ok | {error, ErrorDesc}
542
543              Types:
544
545                 Path = path()
546                 Name = driver()
547                 ErrorDesc = pending_process | OpaqueError
548                 OpaqueError = term()
549
550              Works exactly as reload/2,  but  for  drivers  loaded  with  the
551              load_driver/2 interface.
552
553              As  this  interface  implies that ports are killed when the last
554              user disappears, the function does not hang waiting for ports to
555              get closed.
556
557              For  more  details, see scenarios in this module description and
558              the function description for reload/2.
559
560              The function throws a badarg exception if the parameters are not
561              specified as described here.
562
563       try_load(Path, Name, OptionList) ->
564                   {ok, Status} |
565                   {ok, PendingStatus, Ref} |
566                   {error, ErrorDesc}
567
568              Types:
569
570                 Path = path()
571                 Name = driver()
572                 OptionList = [Option]
573                 Option =
574                     {driver_options, DriverOptionList} |
575                     {monitor, MonitorOption} |
576                     {reload, ReloadOption}
577                 DriverOptionList = [DriverOption]
578                 DriverOption = kill_ports
579                 MonitorOption = ReloadOption = pending_driver | pending
580                 Status = loaded | already_loaded | PendingStatus
581                 PendingStatus = pending_driver | pending_process
582                 Ref = reference()
583                 ErrorDesc = ErrorAtom | OpaqueError
584                 ErrorAtom =
585                     linked_in_driver | inconsistent | permanent |
586                     not_loaded_by_this_process  | not_loaded | pending_reload
587                 |
588                     pending_process
589                 OpaqueError = term()
590
591              Provides   more   control   than   the    load/2/reload/2    and
592              load_driver/2/reload_driver/2  interfaces.  It  never  waits for
593              completion of other operations related to the driver, but  imme‐
594              diately  returns  the status of the driver as one of the follow‐
595              ing:
596
597                {ok, loaded}:
598                  The driver was loaded and is immediately usable.
599
600                {ok, already_loaded}:
601                  The driver was already loaded by another process  or  is  in
602                  use by a living port, or both. The load by you is registered
603                  and a corresponding try_unload is expected sometime  in  the
604                  future.
605
606                {ok, pending_driver}or {ok, pending_driver, reference()}:
607                  The  load  request is registered, but the loading is delayed
608                  because an earlier instance of the driver is  still  waiting
609                  to  get  unloaded  (open  ports  use  it).  Still, unload is
610                  expected when you are done  with  the  driver.  This  return
611                  value  mostly occurs when options {reload,pending_driver} or
612                  {reload,pending} are used, but can occur when  another  user
613                  is   unloading  a  driver  in  parallel  and  driver  option
614                  kill_ports is set. In other words, this return value  always
615                  needs to be handled.
616
617                {ok, pending_process}or {ok, pending_process, reference()}:
618                  The  load  request is registered, but the loading is delayed
619                  because an earlier instance of the driver is  still  waiting
620                  to  get  unloaded  by  another  user (not only by a port, in
621                  which case {ok,pending_driver} would  have  been  returned).
622                  Still, unload is expected when you are done with the driver.
623                  This return value only occurs when  option  {reload,pending}
624                  is used.
625
626              When  the  function  returns  {ok, pending_driver} or {ok, pend‐
627              ing_process}, one can get information about when the  driver  is
628              actually loaded by using option {monitor, MonitorOption}.
629
630              When  monitoring  is  requested,  and a corresponding {ok, pend‐
631              ing_driver} or {ok,  pending_process}  would  be  returned,  the
632              function  instead  returns  a  tuple  {ok, PendingStatus, refer‐
633              ence()} and the process then gets a monitor message later,  when
634              the  driver  gets  loaded.  The  monitor  message  to  expect is
635              described in the function description of monitor/2.
636
637          Note:
638              In case of loading, monitoring can not  only  get  triggered  by
639              using  option  {reload, ReloadOption}, but also in special cases
640              where  the  load  error  is  transient.  Thus,  {monitor,  pend‐
641              ing_driver} is to be used under basically all real world circum‐
642              stances.
643
644
645              The function accepts the following parameters:
646
647                Path:
648                  The file system path  to  the  directory  where  the  driver
649                  object  file  is  located.  The  filename of the object file
650                  (minus extension) must correspond to the driver  name  (used
651                  in  parameter Name) and the driver must identify itself with
652                  the same name. Path can be provided as an iolist(),  meaning
653                  it can be a list of other iolist()s, characters (8-bit inte‐
654                  gers), or binaries, all to be flattened into a  sequence  of
655                  characters.
656
657                  The  (possibly  flattened) Path parameter must be consistent
658                  throughout the system. A driver is  to,  by  all  users,  be
659                  loaded  using  the  same literal Path. The exception is when
660                  reloading is requested, in which case Path can be  specified
661                  differently. Notice that all users trying to load the driver
662                  later need to use the new Path if Path is  changed  using  a
663                  reload  option.  This is yet another reason to have only one
664                  loader of a driver one wants to upgrade in a running system.
665
666                Name:
667                  This parameter is the name of the driver to be used in  sub‐
668                  sequent calls to function erlang:open_port in ERTS. The name
669                  can be specified as an iolist() or an atom(). The name spec‐
670                  ified when loading is used to find the object file (with the
671                  help of Path and the system-implied extension  suffix,  that
672                  is,  .so).  The  name  by which the driver identifies itself
673                  must also be consistent with this Name  parameter,  much  as
674                  the module name of a Beam file much corresponds to its file‐
675                  name.
676
677                OptionList:
678                  Some options can be specified to control the loading  opera‐
679                  tion. The options are specified as a list of two-tuples. The
680                  tuples have the following values and meanings:
681
682                  {driver_options, DriverOptionList}:
683                    This is to provide options that changes its general behav‐
684                    ior and "sticks" to the driver throughout its lifespan.
685
686                    The driver options for a specified driver name need always
687                    to be consistent, even when the driver is reloaded,  mean‐
688                    ing  that  they  are  as  much a part of the driver as the
689                    name.
690
691                    The only allowed driver option is kill_ports, which  means
692                    that  all  ports opened to the driver are killed with exit
693                    reason driver_unloaded when no process any longer has  the
694                    driver  loaded. This situation arises either when the last
695                    user calls try_unload/2, or when the last  process  having
696                    loaded the driver exits.
697
698                  {monitor, MonitorOption}:
699                    A MonitorOption tells try_load/3 to trigger a driver moni‐
700                    tor under certain conditions. When the  monitor  is  trig‐
701                    gered, the function returns a three-tuple {ok, PendingSta‐
702                    tus, reference()}, where reference() is the monitor refer‐
703                    ence for the driver monitor.
704
705                    Only  one MonitorOption can be specified. It is one of the
706                    following:
707
708                    * The atom pending, which means that a monitor  is  to  be
709                      created whenever a load operation is delayed,
710
711                    * The  atom  pending_driver, in which a monitor is created
712                      whenever the operation is delayed because of open  ports
713                      to an otherwise unused driver.
714
715                    Option pending_driver is of little use, but is present for
716                    completeness, as it is well defined which  reload  options
717                    that  can  give rise to which delays. However, it can be a
718                    good idea to use the same MonitorOption as  the  ReloadOp‐
719                    tion, if present.
720
721                    If  reloading  is not requested, it can still be useful to
722                    specify option monitor, as forced unloads  (driver  option
723                    kill_ports or option kill_ports to try_unload/2) trigger a
724                    transient state where driver loading cannot  be  performed
725                    until  all  closing  ports are closed. Thus, as try_unload
726                    can,  in  almost  all  situations,   return   {ok,   pend‐
727                    ing_driver},  always  specify  at  least  {monitor,  pend‐
728                    ing_driver} in production code (see the monitor discussion
729                    earlier).
730
731                  {reload, ReloadOption}:
732                    This  option  is  used  to reload a driver from disk, most
733                    often in a code upgrade scenario. Having a  reload  option
734                    also  implies that parameter Path does not need to be con‐
735                    sistent with earlier loads of the driver.
736
737                    To reload a driver,  the  process  must  have  loaded  the
738                    driver  before,  that  is, there must be an active user of
739                    the driver in the process.
740
741                    The reload option can be either of the following:
742
743                    pending:
744                      With the atom pending, reloading is  requested  for  any
745                      driver  and  is effectuated when all ports opened to the
746                      driver are closed. The driver replacement in  this  case
747                      takes  place regardless if there are still pending users
748                      having the driver loaded.
749
750                      The option also triggers port-killing (if driver  option
751                      kill_ports  is  used)  although there are pending users,
752                      making it usable for forced driver replacement, but lay‐
753                      ing much responsibility on the driver users. The pending
754                      option is seldom used as one does not want  other  users
755                      to have loaded the driver when code change is underway.
756
757                    pending_driver:
758                      This option is more useful. Here, reloading is queued if
759                      the driver is not loaded by any  other  users,  but  the
760                      driver  has  opened  ports,  in  which  case  {ok, pend‐
761                      ing_driver} is returned  (a  monitor  option  is  recom‐
762                      mended).
763
764                    If  the  driver  is  unloaded (not present in the system),
765                    error  code  not_loaded  is  returned.  Option  reload  is
766                    intended  for  when the user has already loaded the driver
767                    in advance.
768
769              The function can  return  numerous  errors,  some  can  only  be
770              returned given a certain combination of options.
771
772              Some  errors  are  opaque and can only be interpreted by passing
773              them to function format_error/1, but  some  can  be  interpreted
774              directly:
775
776                {error,linked_in_driver}:
777                  The  driver  with the specified name is an Erlang statically
778                  linked-in driver, which cannot be manipulated with this API.
779
780                {error,inconsistent}:
781                  The driver is already loaded with other DriverOptionList  or
782                  a different literal Path argument.
783
784                  This  can  occur  even  if  a reload option is specified, if
785                  DriverOptionList differs from the current.
786
787                {error, permanent}:
788                  The driver has requested itself to be permanent,  making  it
789                  behave  like an Erlang linked-in driver and can no longer be
790                  manipulated with this API.
791
792                {error, pending_process}:
793                  The driver is loaded by other  users  when  option  {reload,
794                  pending_driver} was specified.
795
796                {error, pending_reload}:
797                  Driver  reload  is  already  requested  by another user when
798                  option {reload, ReloadOption} was specified.
799
800                {error, not_loaded_by_this_process}:
801                  Appears when option reload is specified. The driver Name  is
802                  present  in  the  system, but there is no user of it in this
803                  process.
804
805                {error, not_loaded}:
806                  Appears when option reload is specified. The driver Name  is
807                  not  in  the system. Only drivers loaded by this process can
808                  be reloaded.
809
810              All other error codes are to  be  translated  by  function  for‐
811              mat_error/1.  Notice  that  calls to format_error are to be per‐
812              formed from the same running  instance  of  the  Erlang  virtual
813              machine as the error is detected in, because of system-dependent
814              behavior concerning error values.
815
816              If the arguments or options are malformed, the function throws a
817              badarg exception.
818
819       try_unload(Name, OptionList) ->
820                     {ok, Status} |
821                     {ok, PendingStatus, Ref} |
822                     {error, ErrorAtom}
823
824              Types:
825
826                 Name = driver()
827                 OptionList = [Option]
828                 Option = {monitor, MonitorOption} | kill_ports
829                 MonitorOption = pending_driver | pending
830                 Status = unloaded | PendingStatus
831                 PendingStatus = pending_driver | pending_process
832                 Ref = reference()
833                 ErrorAtom =
834                     linked_in_driver          |          not_loaded         |
835                 not_loaded_by_this_process |
836                     permanent
837
838              This is the low-level function to unload (or decrement reference
839              counts  of)  a  driver. It can be used to force port killing, in
840              much the same way as the  driver  option  kill_ports  implicitly
841              does.  Also, it can trigger a monitor either because other users
842              still have the driver loaded  or  because  open  ports  use  the
843              driver.
844
845              Unloading  can be described as the process of telling the emula‐
846              tor that this particular part of the  code  in  this  particular
847              process  (that  is,  this user) no longer needs the driver. That
848              can, if there are no  other  users,  trigger  unloading  of  the
849              driver, in which case the driver name disappears from the system
850              and (if possible) the memory occupied by the  driver  executable
851              code is reclaimed.
852
853              If  the  driver  has  option kill_ports set, or if kill_ports is
854              specified as an option to this function, all pending ports using
855              this  driver are killed when unloading is done by the last user.
856              If no port-killing is involved and there  are  open  ports,  the
857              unloading  is  delayed  until no more open ports use the driver.
858              If, in this case, another user (or even  this  user)  loads  the
859              driver  again before the driver is unloaded, the unloading never
860              takes place.
861
862              To allow the user  to  request  unloading  to  wait  for  actual
863              unloading,  monitor  triggers  can be specified in much the same
864              way as when loading. However, as users of this  function  seldom
865              are  interested  in more than decrementing the reference counts,
866              monitoring is seldom needed.
867
868          Note:
869              If option kill_ports is used, monitor trigging  is  crucial,  as
870              the  ports  are  not guaranteed to be killed until the driver is
871              unloaded. Thus, a monitor must be triggered  for  at  least  the
872              pending_driver case.
873
874
875              The  possible  monitor  messages  to expect are the same as when
876              using option unloaded to function monitor/2.
877
878              The function returns one of the following statuses upon success:
879
880                {ok, unloaded}:
881                  The driver was immediately unloaded, meaning that the driver
882                  name  is now free to use by other drivers and, if the under‐
883                  lying OS permits it,  the  memory  occupied  by  the  driver
884                  object code is now reclaimed.
885
886                  The driver can only be unloaded when there are no open ports
887                  using it and no more users require it to be loaded.
888
889                {ok, pending_driver}or {ok, pending_driver, reference()}:
890                  Indicates that this call removed  the  last  user  from  the
891                  driver,  but  there  are still open ports using it. When all
892                  ports are closed and no new users have arrived,  the  driver
893                  is reloaded and the name and memory reclaimed.
894
895                  This  return  value  is  valid even if option kill_ports was
896                  used, as killing ports can be a process that does  not  com‐
897                  plete  immediately.  However,  the condition is in that case
898                  transient. Monitors are always useful  to  detect  when  the
899                  driver is really unloaded.
900
901                {ok, pending_process}or {ok, pending_process, reference()}:
902                  The unload request is registered, but other users still hold
903                  the driver. Notice that the term pending_process  can  refer
904                  to  the  running process; there can be more than one user in
905                  the same process.
906
907                  This is a normal, healthy, return value if the call was just
908                  placed  to  inform the emulator that you have no further use
909                  of the driver. It is the most common  return  value  in  the
910                  most common scenario described in the introduction.
911
912              The function accepts the following parameters:
913
914                Name:
915                  Name  is the name of the driver to be unloaded. The name can
916                  be specified as an iolist() or as an atom().
917
918                OptionList:
919                  Argument OptionList can be used to specify certain  behavior
920                  regarding ports and triggering monitors under certain condi‐
921                  tions:
922
923                  kill_ports:
924                    Forces killing of all ports opened using this driver, with
925                    exit  reason  driver_unloaded, if you are the last user of
926                    the driver.
927
928                    If other users have the driver loaded, this option has  no
929                    effect.
930
931                    To  get  the consistent behavior of killing ports when the
932                    last user unloads, use driver option kill_ports when load‐
933                    ing the driver instead.
934
935                  {monitor, MonitorOption}:
936                    Creates  a  driver  monitor  if the condition specified in
937                    MonitorOption is true. The valid options are:
938
939                    pending_driver:
940                      Creates a driver monitor if the return value  is  to  be
941                      {ok, pending_driver}.
942
943                    pending:
944                      Creates  a  monitor  if  the  return value is {ok, pend‐
945                      ing_driver} or {ok, pending_process}.
946
947                    The pending_driver MonitorOption is by far the  most  use‐
948                    ful.  It  must be used to ensure that the driver really is
949                    unloaded and the ports closed whenever  option  kill_ports
950                    is  used,  or  the driver can have been loaded with driver
951                    option kill_ports.
952
953                    Using the monitor  triggers  in  the  call  to  try_unload
954                    ensures  that the monitor is added before the unloading is
955                    executed, meaning that  the  monitor  is  always  properly
956                    triggered,  which  is  not the case if monitor/2 is called
957                    separately.
958
959              The function can return the following error conditions, all well
960              specified (no opaque values):
961
962                {error, linked_in_driver}:
963                  You  were  trying  to  unload an Erlang statically linked-in
964                  driver, which cannot be manipulated with this interface (and
965                  cannot be unloaded at all).
966
967                {error, not_loaded}:
968                  The driver Name is not present in the system.
969
970                {error, not_loaded_by_this_process}:
971                  The  driver  Name  is present in the system, but there is no
972                  user of it in this process.
973
974                  As a special case, drivers can be  unloaded  from  processes
975                  that  have  done no corresponding call to try_load/3 if, and
976                  only if, there are no users of the driver at all, which  can
977                  occur if the process containing the last user dies.
978
979                {error, permanent}:
980                  The  driver  has made itself permanent, in which case it can
981                  no longer be manipulated by  this  interface  (much  like  a
982                  statically linked-in driver).
983
984              The function throws a badarg exception if the parameters are not
985              specified as described here.
986
987       unload(Name) -> ok | {error, ErrorDesc}
988
989              Types:
990
991                 Name = driver()
992                 ErrorDesc = term()
993
994              Unloads, or at least dereferences the driver named Name. If  the
995              caller  is  the  last user of the driver, and no more open ports
996              use the driver, the driver gets unloaded.  Otherwise,  unloading
997              is delayed until all ports are closed and no users remain.
998
999              If  there are other users of the driver, the reference counts of
1000              the driver is merely decreased, so that the caller is no  longer
1001              considered  a  user  of  the  driver. For use scenarios, see the
1002              description in the beginning of this module.
1003
1004              The ErrorDesc returned is an opaque value to be  passed  further
1005              on  to function format_error/1. For more control over the opera‐
1006              tion, use the try_unload/2 interface.
1007
1008              The function throws a badarg exception if the parameters are not
1009              specified as described here.
1010
1011       unload_driver(Name) -> ok | {error, ErrorDesc}
1012
1013              Types:
1014
1015                 Name = driver()
1016                 ErrorDesc = term()
1017
1018              Unloads,  or at least dereferences the driver named Name. If the
1019              caller is the last user of the driver, all remaining open  ports
1020              using  the driver are killed with reason driver_unloaded and the
1021              driver eventually gets unloaded.
1022
1023              If there are other users of the driver, the reference counts  of
1024              the  driver is merely decreased, so that the caller is no longer
1025              considered a user. For use scenarios, see the description in the
1026              beginning of this module.
1027
1028              The  ErrorDesc  returned is an opaque value to be passed further
1029              on to function format_error/1. For more control over the  opera‐
1030              tion, use the try_unload/2 interface.
1031
1032              The function throws a badarg exception if the parameters are not
1033              specified as described here.
1034

SEE ALSO

1036       erts:erl_driver(4), erts:driver_entry(4)
1037
1038
1039
1040Ericsson AB                       kernel 7.3                       erl_ddll(3)
Impressum