<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html xmlns:fn="http://www.w3.org/2005/02/xpath-functions"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css"> <title>Erlang -- erl_ddll</title> </head> <body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container"> <script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript"> <!-- function getWinHeight() { var myHeight = 0; if( typeof( window.innerHeight ) == 'number' ) { //Non-IE myHeight = window.innerHeight; } else if( document.documentElement && ( document.documentElement.clientWidth || document.documentElement.clientHeight ) ) { //IE 6+ in 'standards compliant mode' myHeight = document.documentElement.clientHeight; } else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) { //IE 4 compatible myHeight = document.body.clientHeight; } return myHeight; } function setscrollpos() { var objf=document.getElementById('loadscrollpos'); document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2; } function addEvent(obj, evType, fn){ if (obj.addEventListener){ obj.addEventListener(evType, fn, true); return true; } else if (obj.attachEvent){ var r = obj.attachEvent("on"+evType, fn); return r; } else { return false; } } addEvent(window, 'load', setscrollpos); //--></script><div id="leftnav"><div class="innertube"> <img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/kernel-2.15.3.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Kernel</strong><br><strong>Reference Manual</strong><br><small>Version 2.15.3</small></p> <br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p> <ul class="flipMenu"> <li title="kernel (App)"><a href="kernel_app.html">kernel (App) </a></li> <li id="no" title="application " expanded="false">application<ul> <li><a href="application.html"> Top of manual page </a></li> <li title="get_all_env-0"><a href="application.html#get_all_env-0">get_all_env/0</a></li> <li title="get_all_env-1"><a href="application.html#get_all_env-1">get_all_env/1</a></li> <li title="get_all_key-0"><a href="application.html#get_all_key-0">get_all_key/0</a></li> <li title="get_all_key-1"><a href="application.html#get_all_key-1">get_all_key/1</a></li> <li title="get_application-0"><a href="application.html#get_application-0">get_application/0</a></li> <li title="get_application-1"><a href="application.html#get_application-1">get_application/1</a></li> <li title="get_env-1"><a href="application.html#get_env-1">get_env/1</a></li> <li title="get_env-2"><a href="application.html#get_env-2">get_env/2</a></li> <li title="get_key-1"><a href="application.html#get_key-1">get_key/1</a></li> <li title="get_key-2"><a href="application.html#get_key-2">get_key/2</a></li> <li title="load-1"><a href="application.html#load-1">load/1</a></li> <li title="load-2"><a href="application.html#load-2">load/2</a></li> <li title="loaded_applications-0"><a href="application.html#loaded_applications-0">loaded_applications/0</a></li> <li title="permit-2"><a href="application.html#permit-2">permit/2</a></li> <li title="set_env-3"><a href="application.html#set_env-3">set_env/3</a></li> <li title="set_env-4"><a href="application.html#set_env-4">set_env/4</a></li> <li title="start-1"><a href="application.html#start-1">start/1</a></li> <li title="start-2"><a href="application.html#start-2">start/2</a></li> <li title="start_type-0"><a href="application.html#start_type-0">start_type/0</a></li> <li title="stop-1"><a href="application.html#stop-1">stop/1</a></li> <li title="takeover-2"><a href="application.html#takeover-2">takeover/2</a></li> <li title="unload-1"><a href="application.html#unload-1">unload/1</a></li> <li title="unset_env-2"><a href="application.html#unset_env-2">unset_env/2</a></li> <li title="unset_env-3"><a href="application.html#unset_env-3">unset_env/3</a></li> <li title="which_applications-0"><a href="application.html#which_applications-0">which_applications/0</a></li> <li title="which_applications-1"><a href="application.html#which_applications-1">which_applications/1</a></li> <li title="Module:start-2"><a href="application.html#Module:start-2">Module:start/2</a></li> <li title="Module:start_phase-3"><a href="application.html#Module:start_phase-3">Module:start_phase/3</a></li> <li title="Module:prep_stop-1"><a href="application.html#Module:prep_stop-1">Module:prep_stop/1</a></li> <li title="Module:stop-1"><a href="application.html#Module:stop-1">Module:stop/1</a></li> <li title="Module:config_change-3"><a href="application.html#Module:config_change-3">Module:config_change/3</a></li> </ul> </li> <li id="no" title="auth " expanded="false">auth<ul> <li><a href="auth.html"> Top of manual page </a></li> <li title="is_auth-1"><a href="auth.html#is_auth-1">is_auth/1</a></li> <li title="cookie-0"><a href="auth.html#cookie-0">cookie/0</a></li> <li title="cookie-1"><a href="auth.html#cookie-1">cookie/1</a></li> <li title="node_cookie-1"><a href="auth.html#node_cookie-1">node_cookie/1</a></li> <li title="node_cookie-2"><a href="auth.html#node_cookie-2">node_cookie/2</a></li> </ul> </li> <li id="no" title="code " expanded="false">code<ul> <li><a href="code.html"> Top of manual page </a></li> <li title="set_path-1"><a href="code.html#set_path-1">set_path/1</a></li> <li title="get_path-0"><a href="code.html#get_path-0">get_path/0</a></li> <li title="add_path-1"><a href="code.html#add_path-1">add_path/1</a></li> <li title="add_pathz-1"><a href="code.html#add_pathz-1">add_pathz/1</a></li> <li title="add_patha-1"><a href="code.html#add_patha-1">add_patha/1</a></li> <li title="add_paths-1"><a href="code.html#add_paths-1">add_paths/1</a></li> <li title="add_pathsz-1"><a href="code.html#add_pathsz-1">add_pathsz/1</a></li> <li title="add_pathsa-1"><a href="code.html#add_pathsa-1">add_pathsa/1</a></li> <li title="del_path-1"><a href="code.html#del_path-1">del_path/1</a></li> <li title="replace_path-2"><a href="code.html#replace_path-2">replace_path/2</a></li> <li title="load_file-1"><a href="code.html#load_file-1">load_file/1</a></li> <li title="load_abs-1"><a href="code.html#load_abs-1">load_abs/1</a></li> <li title="ensure_loaded-1"><a href="code.html#ensure_loaded-1">ensure_loaded/1</a></li> <li title="load_binary-3"><a href="code.html#load_binary-3">load_binary/3</a></li> <li title="delete-1"><a href="code.html#delete-1">delete/1</a></li> <li title="purge-1"><a href="code.html#purge-1">purge/1</a></li> <li title="soft_purge-1"><a href="code.html#soft_purge-1">soft_purge/1</a></li> <li title="is_loaded-1"><a href="code.html#is_loaded-1">is_loaded/1</a></li> <li title="all_loaded-0"><a href="code.html#all_loaded-0">all_loaded/0</a></li> <li title="which-1"><a href="code.html#which-1">which/1</a></li> <li title="get_object_code-1"><a href="code.html#get_object_code-1">get_object_code/1</a></li> <li title="root_dir-0"><a href="code.html#root_dir-0">root_dir/0</a></li> <li title="lib_dir-0"><a href="code.html#lib_dir-0">lib_dir/0</a></li> <li title="lib_dir-1"><a href="code.html#lib_dir-1">lib_dir/1</a></li> <li title="lib_dir-2"><a href="code.html#lib_dir-2">lib_dir/2</a></li> <li title="compiler_dir-0"><a href="code.html#compiler_dir-0">compiler_dir/0</a></li> <li title="priv_dir-1"><a href="code.html#priv_dir-1">priv_dir/1</a></li> <li title="objfile_extension-0"><a href="code.html#objfile_extension-0">objfile_extension/0</a></li> <li title="stick_dir-1"><a href="code.html#stick_dir-1">stick_dir/1</a></li> <li title="unstick_dir-1"><a href="code.html#unstick_dir-1">unstick_dir/1</a></li> <li title="is_sticky-1"><a href="code.html#is_sticky-1">is_sticky/1</a></li> <li title="rehash-0"><a href="code.html#rehash-0">rehash/0</a></li> <li title="where_is_file-1"><a href="code.html#where_is_file-1">where_is_file/1</a></li> <li title="clash-0"><a href="code.html#clash-0">clash/0</a></li> <li title="is_module_native-1"><a href="code.html#is_module_native-1">is_module_native/1</a></li> </ul> </li> <li id="no" title="disk_log " expanded="false">disk_log<ul> <li><a href="disk_log.html"> Top of manual page </a></li> <li title="accessible_logs-0"><a href="disk_log.html#accessible_logs-0">accessible_logs/0</a></li> <li title="alog-2"><a href="disk_log.html#alog-2">alog/2</a></li> <li title="balog-2"><a href="disk_log.html#balog-2">balog/2</a></li> <li title="alog_terms-2"><a href="disk_log.html#alog_terms-2">alog_terms/2</a></li> <li title="balog_terms-2"><a href="disk_log.html#balog_terms-2">balog_terms/2</a></li> <li title="block-1"><a href="disk_log.html#block-1">block/1</a></li> <li title="block-2"><a href="disk_log.html#block-2">block/2</a></li> <li title="change_header-2"><a href="disk_log.html#change_header-2">change_header/2</a></li> <li title="change_notify-3"><a href="disk_log.html#change_notify-3">change_notify/3</a></li> <li title="change_size-2"><a href="disk_log.html#change_size-2">change_size/2</a></li> <li title="chunk-2"><a href="disk_log.html#chunk-2">chunk/2</a></li> <li title="chunk-3"><a href="disk_log.html#chunk-3">chunk/3</a></li> <li title="bchunk-2"><a href="disk_log.html#bchunk-2">bchunk/2</a></li> <li title="bchunk-3"><a href="disk_log.html#bchunk-3">bchunk/3</a></li> <li title="chunk_info-1"><a href="disk_log.html#chunk_info-1">chunk_info/1</a></li> <li title="chunk_step-3"><a href="disk_log.html#chunk_step-3">chunk_step/3</a></li> <li title="close-1"><a href="disk_log.html#close-1">close/1</a></li> <li title="format_error-1"><a href="disk_log.html#format_error-1">format_error/1</a></li> <li title="inc_wrap_file-1"><a href="disk_log.html#inc_wrap_file-1">inc_wrap_file/1</a></li> <li title="info-1"><a href="disk_log.html#info-1">info/1</a></li> <li title="lclose-1"><a href="disk_log.html#lclose-1">lclose/1</a></li> <li title="lclose-2"><a href="disk_log.html#lclose-2">lclose/2</a></li> <li title="log-2"><a href="disk_log.html#log-2">log/2</a></li> <li title="blog-2"><a href="disk_log.html#blog-2">blog/2</a></li> <li title="log_terms-2"><a href="disk_log.html#log_terms-2">log_terms/2</a></li> <li title="blog_terms-2"><a href="disk_log.html#blog_terms-2">blog_terms/2</a></li> <li title="open-1"><a href="disk_log.html#open-1">open/1</a></li> <li title="pid2name-1"><a href="disk_log.html#pid2name-1">pid2name/1</a></li> <li title="reopen-2"><a href="disk_log.html#reopen-2">reopen/2</a></li> <li title="reopen-3"><a href="disk_log.html#reopen-3">reopen/3</a></li> <li title="breopen-3"><a href="disk_log.html#breopen-3">breopen/3</a></li> <li title="sync-1"><a href="disk_log.html#sync-1">sync/1</a></li> <li title="truncate-1"><a href="disk_log.html#truncate-1">truncate/1</a></li> <li title="truncate-2"><a href="disk_log.html#truncate-2">truncate/2</a></li> <li title="btruncate-2"><a href="disk_log.html#btruncate-2">btruncate/2</a></li> <li title="unblock-1"><a href="disk_log.html#unblock-1">unblock/1</a></li> </ul> </li> <li id="no" title="erl_boot_server " expanded="false">erl_boot_server<ul> <li><a href="erl_boot_server.html"> Top of manual page </a></li> <li title="start-1"><a href="erl_boot_server.html#start-1">start/1</a></li> <li title="start_link-1"><a href="erl_boot_server.html#start_link-1">start_link/1</a></li> <li title="add_slave-1"><a href="erl_boot_server.html#add_slave-1">add_slave/1</a></li> <li title="delete_slave-1"><a href="erl_boot_server.html#delete_slave-1">delete_slave/1</a></li> <li title="which_slaves-0"><a href="erl_boot_server.html#which_slaves-0">which_slaves/0</a></li> </ul> </li> <li id="loadscrollpos" title="erl_ddll " expanded="true">erl_ddll<ul> <li><a href="erl_ddll.html"> Top of manual page </a></li> <li title="demonitor-1"><a href="erl_ddll.html#demonitor-1">demonitor/1</a></li> <li title="info-0"><a href="erl_ddll.html#info-0">info/0</a></li> <li title="info-1"><a href="erl_ddll.html#info-1">info/1</a></li> <li title="info-2"><a href="erl_ddll.html#info-2">info/2</a></li> <li title="load-2"><a href="erl_ddll.html#load-2">load/2</a></li> <li title="load_driver-2"><a href="erl_ddll.html#load_driver-2">load_driver/2</a></li> <li title="monitor-2"><a href="erl_ddll.html#monitor-2">monitor/2</a></li> <li title="reload-2"><a href="erl_ddll.html#reload-2">reload/2</a></li> <li title="reload_driver-2"><a href="erl_ddll.html#reload_driver-2">reload_driver/2</a></li> <li title="try_load-3"><a href="erl_ddll.html#try_load-3">try_load/3</a></li> <li title="try_unload-2"><a href="erl_ddll.html#try_unload-2">try_unload/2</a></li> <li title="unload-1"><a href="erl_ddll.html#unload-1">unload/1</a></li> <li title="unload_driver-1"><a href="erl_ddll.html#unload_driver-1">unload_driver/1</a></li> <li title="loaded_drivers-0"><a href="erl_ddll.html#loaded_drivers-0">loaded_drivers/0</a></li> <li title="format_error-1"><a href="erl_ddll.html#format_error-1">format_error/1</a></li> </ul> </li> <li title="erl_prim_loader"><a href="erl_prim_loader.html">erl_prim_loader</a></li> <li title="erlang"><a href="erlang.html">erlang</a></li> <li id="no" title="error_handler " expanded="false">error_handler<ul> <li><a href="error_handler.html"> Top of manual page </a></li> <li title="undefined_function-3"><a href="error_handler.html#undefined_function-3">undefined_function/3</a></li> <li title="undefined_lambda-3"><a href="error_handler.html#undefined_lambda-3">undefined_lambda/3</a></li> </ul> </li> <li id="no" title="error_logger " expanded="false">error_logger<ul> <li><a href="error_logger.html"> Top of manual page </a></li> <li title="error_msg-1"><a href="error_logger.html#error_msg-1">error_msg/1</a></li> <li title="error_msg-2"><a href="error_logger.html#error_msg-2">error_msg/2</a></li> <li title="format-2"><a href="error_logger.html#format-2">format/2</a></li> <li title="error_report-1"><a href="error_logger.html#error_report-1">error_report/1</a></li> <li title="error_report-2"><a href="error_logger.html#error_report-2">error_report/2</a></li> <li title="warning_map-0"><a href="error_logger.html#warning_map-0">warning_map/0</a></li> <li title="warning_msg-1"><a href="error_logger.html#warning_msg-1">warning_msg/1</a></li> <li title="warning_msg-2"><a href="error_logger.html#warning_msg-2">warning_msg/2</a></li> <li title="warning_report-1"><a href="error_logger.html#warning_report-1">warning_report/1</a></li> <li title="warning_report-2"><a href="error_logger.html#warning_report-2">warning_report/2</a></li> <li title="info_msg-1"><a href="error_logger.html#info_msg-1">info_msg/1</a></li> <li title="info_msg-2"><a href="error_logger.html#info_msg-2">info_msg/2</a></li> <li title="info_report-1"><a href="error_logger.html#info_report-1">info_report/1</a></li> <li title="info_report-2"><a href="error_logger.html#info_report-2">info_report/2</a></li> <li title="add_report_handler-1"><a href="error_logger.html#add_report_handler-1">add_report_handler/1</a></li> <li title="add_report_handler-2"><a href="error_logger.html#add_report_handler-2">add_report_handler/2</a></li> <li title="delete_report_handler-1"><a href="error_logger.html#delete_report_handler-1">delete_report_handler/1</a></li> <li title="tty-1"><a href="error_logger.html#tty-1">tty/1</a></li> <li title="logfile-1"><a href="error_logger.html#logfile-1">logfile/1</a></li> </ul> </li> <li id="no" title="file " expanded="false">file<ul> <li><a href="file.html"> Top of manual page </a></li> <li title="advise-4"><a href="file.html#advise-4">advise/4</a></li> <li title="change_group-2"><a href="file.html#change_group-2">change_group/2</a></li> <li title="change_mode-2"><a href="file.html#change_mode-2">change_mode/2</a></li> <li title="change_owner-2"><a href="file.html#change_owner-2">change_owner/2</a></li> <li title="change_owner-3"><a href="file.html#change_owner-3">change_owner/3</a></li> <li title="change_time-2"><a href="file.html#change_time-2">change_time/2</a></li> <li title="change_time-3"><a href="file.html#change_time-3">change_time/3</a></li> <li title="close-1"><a href="file.html#close-1">close/1</a></li> <li title="consult-1"><a href="file.html#consult-1">consult/1</a></li> <li title="copy-2"><a href="file.html#copy-2">copy/2</a></li> <li title="copy-3"><a href="file.html#copy-3">copy/3</a></li> <li title="del_dir-1"><a href="file.html#del_dir-1">del_dir/1</a></li> <li title="delete-1"><a href="file.html#delete-1">delete/1</a></li> <li title="eval-1"><a href="file.html#eval-1">eval/1</a></li> <li title="eval-2"><a href="file.html#eval-2">eval/2</a></li> <li title="file_info-1"><a href="file.html#file_info-1">file_info/1</a></li> <li title="format_error-1"><a href="file.html#format_error-1">format_error/1</a></li> <li title="get_cwd-0"><a href="file.html#get_cwd-0">get_cwd/0</a></li> <li title="get_cwd-1"><a href="file.html#get_cwd-1">get_cwd/1</a></li> <li title="list_dir-1"><a href="file.html#list_dir-1">list_dir/1</a></li> <li title="make_dir-1"><a href="file.html#make_dir-1">make_dir/1</a></li> <li title="make_link-2"><a href="file.html#make_link-2">make_link/2</a></li> <li title="make_symlink-2"><a href="file.html#make_symlink-2">make_symlink/2</a></li> <li title="native_name_encoding-0"><a href="file.html#native_name_encoding-0">native_name_encoding/0</a></li> <li title="open-2"><a href="file.html#open-2">open/2</a></li> <li title="path_consult-2"><a href="file.html#path_consult-2">path_consult/2</a></li> <li title="path_eval-2"><a href="file.html#path_eval-2">path_eval/2</a></li> <li title="path_open-3"><a href="file.html#path_open-3">path_open/3</a></li> <li title="path_script-2"><a href="file.html#path_script-2">path_script/2</a></li> <li title="path_script-3"><a href="file.html#path_script-3">path_script/3</a></li> <li title="pid2name-1"><a href="file.html#pid2name-1">pid2name/1</a></li> <li title="position-2"><a href="file.html#position-2">position/2</a></li> <li title="pread-2"><a href="file.html#pread-2">pread/2</a></li> <li title="pread-3"><a href="file.html#pread-3">pread/3</a></li> <li title="pwrite-2"><a href="file.html#pwrite-2">pwrite/2</a></li> <li title="pwrite-3"><a href="file.html#pwrite-3">pwrite/3</a></li> <li title="read-2"><a href="file.html#read-2">read/2</a></li> <li title="read_file-1"><a href="file.html#read_file-1">read_file/1</a></li> <li title="read_file_info-1"><a href="file.html#read_file_info-1">read_file_info/1</a></li> <li title="read_file_info-2"><a href="file.html#read_file_info-2">read_file_info/2</a></li> <li title="read_line-1"><a href="file.html#read_line-1">read_line/1</a></li> <li title="read_link-1"><a href="file.html#read_link-1">read_link/1</a></li> <li title="read_link_info-1"><a href="file.html#read_link_info-1">read_link_info/1</a></li> <li title="read_link_info-2"><a href="file.html#read_link_info-2">read_link_info/2</a></li> <li title="rename-2"><a href="file.html#rename-2">rename/2</a></li> <li title="script-1"><a href="file.html#script-1">script/1</a></li> <li title="script-2"><a href="file.html#script-2">script/2</a></li> <li title="set_cwd-1"><a href="file.html#set_cwd-1">set_cwd/1</a></li> <li title="sync-1"><a href="file.html#sync-1">sync/1</a></li> <li title="datasync-1"><a href="file.html#datasync-1">datasync/1</a></li> <li title="truncate-1"><a href="file.html#truncate-1">truncate/1</a></li> <li title="sendfile-2"><a href="file.html#sendfile-2">sendfile/2</a></li> <li title="sendfile-5"><a href="file.html#sendfile-5">sendfile/5</a></li> <li title="write-2"><a href="file.html#write-2">write/2</a></li> <li title="write_file-2"><a href="file.html#write_file-2">write_file/2</a></li> <li title="write_file-3"><a href="file.html#write_file-3">write_file/3</a></li> <li title="write_file_info-2"><a href="file.html#write_file_info-2">write_file_info/2</a></li> <li title="write_file_info-3"><a href="file.html#write_file_info-3">write_file_info/3</a></li> </ul> </li> <li id="no" title="gen_tcp " expanded="false">gen_tcp<ul> <li><a href="gen_tcp.html"> Top of manual page </a></li> <li title="connect-3"><a href="gen_tcp.html#connect-3">connect/3</a></li> <li title="connect-4"><a href="gen_tcp.html#connect-4">connect/4</a></li> <li title="listen-2"><a href="gen_tcp.html#listen-2">listen/2</a></li> <li title="accept-1"><a href="gen_tcp.html#accept-1">accept/1</a></li> <li title="accept-2"><a href="gen_tcp.html#accept-2">accept/2</a></li> <li title="send-2"><a href="gen_tcp.html#send-2">send/2</a></li> <li title="recv-2"><a href="gen_tcp.html#recv-2">recv/2</a></li> <li title="recv-3"><a href="gen_tcp.html#recv-3">recv/3</a></li> <li title="controlling_process-2"><a href="gen_tcp.html#controlling_process-2">controlling_process/2</a></li> <li title="close-1"><a href="gen_tcp.html#close-1">close/1</a></li> <li title="shutdown-2"><a href="gen_tcp.html#shutdown-2">shutdown/2</a></li> </ul> </li> <li id="no" title="gen_udp " expanded="false">gen_udp<ul> <li><a href="gen_udp.html"> Top of manual page </a></li> <li title="open-1"><a href="gen_udp.html#open-1">open/1</a></li> <li title="open-2"><a href="gen_udp.html#open-2">open/2</a></li> <li title="send-4"><a href="gen_udp.html#send-4">send/4</a></li> <li title="recv-2"><a href="gen_udp.html#recv-2">recv/2</a></li> <li title="recv-3"><a href="gen_udp.html#recv-3">recv/3</a></li> <li title="controlling_process-2"><a href="gen_udp.html#controlling_process-2">controlling_process/2</a></li> <li title="close-1"><a href="gen_udp.html#close-1">close/1</a></li> </ul> </li> <li id="no" title="gen_sctp " expanded="false">gen_sctp<ul> <li><a href="gen_sctp.html"> Top of manual page </a></li> <li title="abort-2"><a href="gen_sctp.html#abort-2">abort/2</a></li> <li title="close-1"><a href="gen_sctp.html#close-1">close/1</a></li> <li title="connect-4"><a href="gen_sctp.html#connect-4">connect/4</a></li> <li title="connect-5"><a href="gen_sctp.html#connect-5">connect/5</a></li> <li title="connect_init-4"><a href="gen_sctp.html#connect_init-4">connect_init/4</a></li> <li title="connect_init-5"><a href="gen_sctp.html#connect_init-5">connect_init/5</a></li> <li title="controlling_process-2"><a href="gen_sctp.html#controlling_process-2">controlling_process/2</a></li> <li title="eof-2"><a href="gen_sctp.html#eof-2">eof/2</a></li> <li title="listen-2"><a href="gen_sctp.html#listen-2">listen/2</a></li> <li title="open-0"><a href="gen_sctp.html#open-0">open/0</a></li> <li title="open-1"><a href="gen_sctp.html#open-1">open/1</a></li> <li title="open-2"><a href="gen_sctp.html#open-2">open/2</a></li> <li title="peeloff-2"><a href="gen_sctp.html#peeloff-2">peeloff/2</a></li> <li title="recv-1"><a href="gen_sctp.html#recv-1">recv/1</a></li> <li title="recv-2"><a href="gen_sctp.html#recv-2">recv/2</a></li> <li title="send-3"><a href="gen_sctp.html#send-3">send/3</a></li> <li title="send-4"><a href="gen_sctp.html#send-4">send/4</a></li> <li title="error_string-1"><a href="gen_sctp.html#error_string-1">error_string/1</a></li> </ul> </li> <li id="no" title="global " expanded="false">global<ul> <li><a href="global.html"> Top of manual page </a></li> <li title="del_lock-1"><a href="global.html#del_lock-1">del_lock/1</a></li> <li title="del_lock-2"><a href="global.html#del_lock-2">del_lock/2</a></li> <li title="notify_all_name-3"><a href="global.html#notify_all_name-3">notify_all_name/3</a></li> <li title="random_exit_name-3"><a href="global.html#random_exit_name-3">random_exit_name/3</a></li> <li title="random_notify_name-3"><a href="global.html#random_notify_name-3">random_notify_name/3</a></li> <li title="register_name-2"><a href="global.html#register_name-2">register_name/2</a></li> <li title="register_name-3"><a href="global.html#register_name-3">register_name/3</a></li> <li title="registered_names-0"><a href="global.html#registered_names-0">registered_names/0</a></li> <li title="re_register_name-2"><a href="global.html#re_register_name-2">re_register_name/2</a></li> <li title="re_register_name-3"><a href="global.html#re_register_name-3">re_register_name/3</a></li> <li title="send-2"><a href="global.html#send-2">send/2</a></li> <li title="set_lock-1"><a href="global.html#set_lock-1">set_lock/1</a></li> <li title="set_lock-2"><a href="global.html#set_lock-2">set_lock/2</a></li> <li title="set_lock-3"><a href="global.html#set_lock-3">set_lock/3</a></li> <li title="sync-0"><a href="global.html#sync-0">sync/0</a></li> <li title="trans-2"><a href="global.html#trans-2">trans/2</a></li> <li title="trans-3"><a href="global.html#trans-3">trans/3</a></li> <li title="trans-4"><a href="global.html#trans-4">trans/4</a></li> <li title="unregister_name-1"><a href="global.html#unregister_name-1">unregister_name/1</a></li> <li title="whereis_name-1"><a href="global.html#whereis_name-1">whereis_name/1</a></li> </ul> </li> <li id="no" title="global_group " expanded="false">global_group<ul> <li><a href="global_group.html"> Top of manual page </a></li> <li title="global_groups-0"><a href="global_group.html#global_groups-0">global_groups/0</a></li> <li title="info-0"><a href="global_group.html#info-0">info/0</a></li> <li title="monitor_nodes-1"><a href="global_group.html#monitor_nodes-1">monitor_nodes/1</a></li> <li title="own_nodes-0"><a href="global_group.html#own_nodes-0">own_nodes/0</a></li> <li title="registered_names-1"><a href="global_group.html#registered_names-1">registered_names/1</a></li> <li title="send-2"><a href="global_group.html#send-2">send/2</a></li> <li title="send-3"><a href="global_group.html#send-3">send/3</a></li> <li title="sync-0"><a href="global_group.html#sync-0">sync/0</a></li> <li title="whereis_name-1"><a href="global_group.html#whereis_name-1">whereis_name/1</a></li> <li title="whereis_name-2"><a href="global_group.html#whereis_name-2">whereis_name/2</a></li> </ul> </li> <li id="no" title="heart " expanded="false">heart<ul> <li><a href="heart.html"> Top of manual page </a></li> <li title="set_cmd-1"><a href="heart.html#set_cmd-1">set_cmd/1</a></li> <li title="clear_cmd-0"><a href="heart.html#clear_cmd-0">clear_cmd/0</a></li> <li title="get_cmd-0"><a href="heart.html#get_cmd-0">get_cmd/0</a></li> </ul> </li> <li id="no" title="inet " expanded="false">inet<ul> <li><a href="inet.html"> Top of manual page </a></li> <li title="close-1"><a href="inet.html#close-1">close/1</a></li> <li title="get_rc-0"><a href="inet.html#get_rc-0">get_rc/0</a></li> <li title="format_error-1"><a href="inet.html#format_error-1">format_error/1</a></li> <li title="getaddr-2"><a href="inet.html#getaddr-2">getaddr/2</a></li> <li title="getaddrs-2"><a href="inet.html#getaddrs-2">getaddrs/2</a></li> <li title="gethostbyaddr-1"><a href="inet.html#gethostbyaddr-1">gethostbyaddr/1</a></li> <li title="gethostbyname-1"><a href="inet.html#gethostbyname-1">gethostbyname/1</a></li> <li title="gethostbyname-2"><a href="inet.html#gethostbyname-2">gethostbyname/2</a></li> <li title="gethostname-0"><a href="inet.html#gethostname-0">gethostname/0</a></li> <li title="getifaddrs-0"><a href="inet.html#getifaddrs-0">getifaddrs/0</a></li> <li title="getopts-2"><a href="inet.html#getopts-2">getopts/2</a></li> <li title="getstat-1"><a href="inet.html#getstat-1">getstat/1</a></li> <li title="getstat-2"><a href="inet.html#getstat-2">getstat/2</a></li> <li title="peername-1"><a href="inet.html#peername-1">peername/1</a></li> <li title="port-1"><a href="inet.html#port-1">port/1</a></li> <li title="sockname-1"><a href="inet.html#sockname-1">sockname/1</a></li> <li title="setopts-2"><a href="inet.html#setopts-2">setopts/2</a></li> </ul> </li> <li id="no" title="inet_res " expanded="false">inet_res<ul> <li><a href="inet_res.html"> Top of manual page </a></li> <li title="getbyname-2"><a href="inet_res.html#getbyname-2">getbyname/2</a></li> <li title="getbyname-3"><a href="inet_res.html#getbyname-3">getbyname/3</a></li> <li title="gethostbyaddr-1"><a href="inet_res.html#gethostbyaddr-1">gethostbyaddr/1</a></li> <li title="gethostbyaddr-2"><a href="inet_res.html#gethostbyaddr-2">gethostbyaddr/2</a></li> <li title="gethostbyname-1"><a href="inet_res.html#gethostbyname-1">gethostbyname/1</a></li> <li title="gethostbyname-2"><a href="inet_res.html#gethostbyname-2">gethostbyname/2</a></li> <li title="gethostbyname-3"><a href="inet_res.html#gethostbyname-3">gethostbyname/3</a></li> <li title="lookup-3"><a href="inet_res.html#lookup-3">lookup/3</a></li> <li title="lookup-4"><a href="inet_res.html#lookup-4">lookup/4</a></li> <li title="lookup-5"><a href="inet_res.html#lookup-5">lookup/5</a></li> <li title="resolve-3"><a href="inet_res.html#resolve-3">resolve/3</a></li> <li title="resolve-4"><a href="inet_res.html#resolve-4">resolve/4</a></li> <li title="resolve-5"><a href="inet_res.html#resolve-5">resolve/5</a></li> <li title="nslookup-3"><a href="inet_res.html#nslookup-3">nslookup/3</a></li> <li title="nslookup-4"><a href="inet_res.html#nslookup-4">nslookup/4</a></li> <li title="nnslookup-4"><a href="inet_res.html#nnslookup-4">nnslookup/4</a></li> <li title="nnslookup-5"><a href="inet_res.html#nnslookup-5">nnslookup/5</a></li> </ul> </li> <li title="init"><a href="init.html">init</a></li> <li id="no" title="net_adm " expanded="false">net_adm<ul> <li><a href="net_adm.html"> Top of manual page </a></li> <li title="dns_hostname-1"><a href="net_adm.html#dns_hostname-1">dns_hostname/1</a></li> <li title="host_file-0"><a href="net_adm.html#host_file-0">host_file/0</a></li> <li title="localhost-0"><a href="net_adm.html#localhost-0">localhost/0</a></li> <li title="names-0"><a href="net_adm.html#names-0">names/0</a></li> <li title="names-1"><a href="net_adm.html#names-1">names/1</a></li> <li title="ping-1"><a href="net_adm.html#ping-1">ping/1</a></li> <li title="world-0"><a href="net_adm.html#world-0">world/0</a></li> <li title="world-1"><a href="net_adm.html#world-1">world/1</a></li> <li title="world_list-1"><a href="net_adm.html#world_list-1">world_list/1</a></li> <li title="world_list-2"><a href="net_adm.html#world_list-2">world_list/2</a></li> </ul> </li> <li id="no" title="net_kernel " expanded="false">net_kernel<ul> <li><a href="net_kernel.html"> Top of manual page </a></li> <li title="allow-1"><a href="net_kernel.html#allow-1">allow/1</a></li> <li title="connect_node-1"><a href="net_kernel.html#connect_node-1">connect_node/1</a></li> <li title="monitor_nodes-1"><a href="net_kernel.html#monitor_nodes-1">monitor_nodes/1</a></li> <li title="monitor_nodes-2"><a href="net_kernel.html#monitor_nodes-2">monitor_nodes/2</a></li> <li title="get_net_ticktime-0"><a href="net_kernel.html#get_net_ticktime-0">get_net_ticktime/0</a></li> <li title="set_net_ticktime-1"><a href="net_kernel.html#set_net_ticktime-1">set_net_ticktime/1</a></li> <li title="set_net_ticktime-2"><a href="net_kernel.html#set_net_ticktime-2">set_net_ticktime/2</a></li> <li title="start-1"><a href="net_kernel.html#start-1">start/1</a></li> <li title="start-1"><a href="net_kernel.html#start-1">start/1</a></li> <li title="start-1"><a href="net_kernel.html#start-1">start/1</a></li> <li title="stop-0"><a href="net_kernel.html#stop-0">stop/0</a></li> </ul> </li> <li id="no" title="os " expanded="false">os<ul> <li><a href="os.html"> Top of manual page </a></li> <li title="cmd-1"><a href="os.html#cmd-1">cmd/1</a></li> <li title="find_executable-1"><a href="os.html#find_executable-1">find_executable/1</a></li> <li title="find_executable-2"><a href="os.html#find_executable-2">find_executable/2</a></li> <li title="getenv-0"><a href="os.html#getenv-0">getenv/0</a></li> <li title="getenv-1"><a href="os.html#getenv-1">getenv/1</a></li> <li title="getpid-0"><a href="os.html#getpid-0">getpid/0</a></li> <li title="putenv-2"><a href="os.html#putenv-2">putenv/2</a></li> <li title="timestamp-0"><a href="os.html#timestamp-0">timestamp/0</a></li> <li title="type-0"><a href="os.html#type-0">type/0</a></li> <li title="version-0"><a href="os.html#version-0">version/0</a></li> </ul> </li> <li id="no" title="pg2 " expanded="false">pg2<ul> <li><a href="pg2.html"> Top of manual page </a></li> <li title="create-1"><a href="pg2.html#create-1">create/1</a></li> <li title="delete-1"><a href="pg2.html#delete-1">delete/1</a></li> <li title="get_closest_pid-1"><a href="pg2.html#get_closest_pid-1">get_closest_pid/1</a></li> <li title="get_members-1"><a href="pg2.html#get_members-1">get_members/1</a></li> <li title="get_local_members-1"><a href="pg2.html#get_local_members-1">get_local_members/1</a></li> <li title="join-2"><a href="pg2.html#join-2">join/2</a></li> <li title="leave-2"><a href="pg2.html#leave-2">leave/2</a></li> <li title="which_groups-0"><a href="pg2.html#which_groups-0">which_groups/0</a></li> <li title="start-0"><a href="pg2.html#start-0">start/0</a></li> <li title="start_link-0"><a href="pg2.html#start_link-0">start_link/0</a></li> </ul> </li> <li id="no" title="rpc " expanded="false">rpc<ul> <li><a href="rpc.html"> Top of manual page </a></li> <li title="call-4"><a href="rpc.html#call-4">call/4</a></li> <li title="call-5"><a href="rpc.html#call-5">call/5</a></li> <li title="block_call-4"><a href="rpc.html#block_call-4">block_call/4</a></li> <li title="block_call-5"><a href="rpc.html#block_call-5">block_call/5</a></li> <li title="async_call-4"><a href="rpc.html#async_call-4">async_call/4</a></li> <li title="yield-1"><a href="rpc.html#yield-1">yield/1</a></li> <li title="nb_yield-1"><a href="rpc.html#nb_yield-1">nb_yield/1</a></li> <li title="nb_yield-2"><a href="rpc.html#nb_yield-2">nb_yield/2</a></li> <li title="multicall-3"><a href="rpc.html#multicall-3">multicall/3</a></li> <li title="multicall-4"><a href="rpc.html#multicall-4">multicall/4</a></li> <li title="multicall-5"><a href="rpc.html#multicall-5">multicall/5</a></li> <li title="cast-4"><a href="rpc.html#cast-4">cast/4</a></li> <li title="eval_everywhere-3"><a href="rpc.html#eval_everywhere-3">eval_everywhere/3</a></li> <li title="eval_everywhere-4"><a href="rpc.html#eval_everywhere-4">eval_everywhere/4</a></li> <li title="abcast-2"><a href="rpc.html#abcast-2">abcast/2</a></li> <li title="abcast-3"><a href="rpc.html#abcast-3">abcast/3</a></li> <li title="sbcast-2"><a href="rpc.html#sbcast-2">sbcast/2</a></li> <li title="sbcast-3"><a href="rpc.html#sbcast-3">sbcast/3</a></li> <li title="server_call-4"><a href="rpc.html#server_call-4">server_call/4</a></li> <li title="multi_server_call-2"><a href="rpc.html#multi_server_call-2">multi_server_call/2</a></li> <li title="multi_server_call-3"><a href="rpc.html#multi_server_call-3">multi_server_call/3</a></li> <li title="safe_multi_server_call-2"><a href="rpc.html#safe_multi_server_call-2">safe_multi_server_call/2</a></li> <li title="safe_multi_server_call-3"><a href="rpc.html#safe_multi_server_call-3">safe_multi_server_call/3</a></li> <li title="parallel_eval-1"><a href="rpc.html#parallel_eval-1">parallel_eval/1</a></li> <li title="pmap-3"><a href="rpc.html#pmap-3">pmap/3</a></li> <li title="pinfo-1"><a href="rpc.html#pinfo-1">pinfo/1</a></li> <li title="pinfo-2"><a href="rpc.html#pinfo-2">pinfo/2</a></li> </ul> </li> <li id="no" title="seq_trace " expanded="false">seq_trace<ul> <li><a href="seq_trace.html"> Top of manual page </a></li> <li title="set_token-1"><a href="seq_trace.html#set_token-1">set_token/1</a></li> <li title="set_token-2"><a href="seq_trace.html#set_token-2">set_token/2</a></li> <li title="get_token-0"><a href="seq_trace.html#get_token-0">get_token/0</a></li> <li title="get_token-1"><a href="seq_trace.html#get_token-1">get_token/1</a></li> <li title="print-1"><a href="seq_trace.html#print-1">print/1</a></li> <li title="print-2"><a href="seq_trace.html#print-2">print/2</a></li> <li title="reset_trace-0"><a href="seq_trace.html#reset_trace-0">reset_trace/0</a></li> <li title="set_system_tracer-1"><a href="seq_trace.html#set_system_tracer-1">set_system_tracer/1</a></li> <li title="get_system_tracer-0"><a href="seq_trace.html#get_system_tracer-0">get_system_tracer/0</a></li> </ul> </li> <li title="user"><a href="user.html">user</a></li> <li id="no" title="wrap_log_reader " expanded="false">wrap_log_reader<ul> <li><a href="wrap_log_reader.html"> Top of manual page </a></li> <li title="chunk-1"><a href="wrap_log_reader.html#chunk-1">chunk/1</a></li> <li title="chunk-2"><a href="wrap_log_reader.html#chunk-2">chunk/2</a></li> <li title="close-1"><a href="wrap_log_reader.html#close-1">close/1</a></li> <li title="open-1"><a href="wrap_log_reader.html#open-1">open/1</a></li> <li title="open-2"><a href="wrap_log_reader.html#open-2">open/2</a></li> </ul> </li> <li title="zlib"><a href="zlib.html">zlib</a></li> <li title="app"><a href="app.html">app</a></li> <li title="config"><a href="config.html">config</a></li> <li title="packages"><a href="packages.html">packages</a></li> </ul> </div></div> <div id="content"> <div class="innertube"> <!-- refpage --><center><h1>erl_ddll</h1></center> <h3>MODULE</h3> <div class="REFBODY">erl_ddll</div> <h3>MODULE SUMMARY</h3> <div class="REFBODY">Dynamic Driver Loader and Linker</div> <h3>DESCRIPTION</h3> <div class="REFBODY"><p> <p>The <span class="code">erl_ddll</span> module provides an interface for loading and unloading <strong>erlang linked in drivers</strong> in runtime.</p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>This is a large reference document. For casual use of the module, as well as for most real world applications, the descriptions of the functions <span class="bold_code"><a href="#load-2">load/2</a></span> and <span class="bold_code"><a href="#unload-1">unload/1</a></span> are enough to get going. </p> </p></div> </div> <p>The driver should be provided as a dynamically linked library in a object code format specific for the platform in use, i. e. <span class="code">.so</span> files on most Unix systems and <span class="code">.ddl</span> files on windows. An erlang linked in driver has to provide specific interfaces to the emulator, so this module is not designed for loading arbitrary dynamic libraries. For further information about erlang drivers, refer to the ERTS reference manual section <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','erts','erl_driver.html');">erl_driver</a></span>.</p> <a name="users"></a> <p>When describing a set of functions, (i.e. a module, a part of a module or an application) executing in a process and wanting to use a ddll-driver, we use the term <strong>user</strong>. There can be several users in one process (different modules needing the same driver) and several processes running the same code, making up several <strong>users</strong> of a driver. In the basic scenario, each user loads the driver before starting to use it and unloads the driver when done. The reference counting keeps track of processes as well as the number of loads by each process, so that the driver will only be unloaded when no one wants it (it has no user). The driver also keeps track of ports that are opened towards it, so that one can delay unloading until all ports are closed or kill all ports using the driver when it is unloaded. </p> <a name="scenarios"></a> <p>The interface supports two basic scenarios of loading and unloading. Each scenario can also have the option of either killing ports when the driver is unloading, or waiting for the ports to close themselves. The scenarios are:</p> <dl> <dt><strong><strong>Load and unload on a "when needed basis"</strong></strong></dt> <dd> <p>This (most common) scenario simply supports that each <span class="bold_code"><a href="#users">user</a></span> of the driver loads it when it is needed and unloads it when the <span class="bold_code"><a href="#users">user</a></span> no longer have any use for it. The driver is always reference counted and as long as a process keeping the driver loaded is still alive, the driver is present in the system.</p> <p>Each <span class="bold_code"><a href="#users">user</a></span> of the driver use <strong>literally</strong> the same pathname for the driver when demanding load, but the <span class="bold_code"><a href="#users">users</a></span> are not really concerned with if the driver is already loaded from the filesystem or if the object code has to be loaded from filesystem.</p> <p>Two pairs of functions support this scenario:</p> <dl> <dt><strong><strong>load/2 and unload/1</strong></strong></dt> <dd> <p>When using the <span class="code">load/unload</span> interfaces, the driver will not <strong>actually</strong> get unloaded until the <strong>last port</strong> using the driver is closed. The function <span class="code">unload/1</span> can return immediately, as the <span class="bold_code"><a href="#users">users</a></span> are not really concerned with when the actual unloading occurs. The driver will actually get unloaded when no one needs it any longer.</p> <p>If a process having the driver loaded dies, it will have the same effect as if unloading was done. </p> <p>When loading, the function <span class="code">load/2</span> returns <span class="code">ok</span> as soon as there is any instance of the driver present, so that if a driver is waiting to get unloaded (due to open ports), it will simply change state to no longer need unloading.</p> </dd> <dt><strong><strong>load_driver/2 and unload_driver/1</strong></strong></dt> <dd> <p>These interfaces is intended to be used when it is considered an error that ports are open towards a driver that no <span class="bold_code"><a href="#users">user</a></span> has loaded. The ports still open when the last <span class="bold_code"><a href="#users">user</a></span> calls <span class="code">unload_driver/1</span> or when the last process having the driver loaded dies, will get killed with reason <span class="code">driver_unloaded</span>.</p> <p>The function names <span class="code">load_driver</span> and <span class="code">unload_driver</span> are kept for backward compatibility.</p> </dd> </dl> </dd> <dt><strong><strong>Loading and reloading for code replacement</strong></strong></dt> <dd> <p>This scenario occurs when the driver code might need replacement during operation of the Erlang emulator. Implementing driver code replacement is somewhat more tedious than beam code replacement, as one driver cannot be loaded as both "old" and "new" code. All <span class="bold_code"><a href="#users">users</a></span> of a driver must have it closed (no open ports) before the old code can be unloaded and the new code can be loaded.</p> <p>The actual unloading/loading is done as one atomic operation, blocking all processes in the system from using the driver concerned while in progress.</p> <p>The preferred way to do driver code replacement is to let <strong>one single process</strong> keep track of the driver. When the process start, the driver is loaded. When replacement is required, the driver is reloaded. Unload is probably never done, or done when the process exits. If more than one <span class="bold_code"><a href="#users">user</a></span> has a driver loaded when code replacement is demanded, the replacement cannot occur until the last "other" <span class="bold_code"><a href="#users">user</a></span> has unloaded the driver.</p> <p>Demanding reload when a reload is already in progress is always an error. Using the high level functions, it is also an error to demand reloading when more than one <span class="bold_code"><a href="#users">user</a></span> has the driver loaded. To simplify driver replacement, avoid designing your system so that more than than one <span class="bold_code"><a href="#users">user</a></span> has the driver loaded.</p> <p>The two functions for reloading drivers should be used together with corresponding load functions, to support the two different behaviors concerning open ports:</p> <dl> <dt><strong><strong>load/2 and reload/2</strong></strong></dt> <dd> <p>This pair of functions is used when reloading should be done after the last open port towards the driver is closed.</p> <p>As <span class="code">reload/2</span> actually waits for the reloading to occur, a misbehaving process keeping open ports towards the driver (or keeping the driver loaded) might cause infinite waiting for reload. Timeouts has to be provided outside of the process demanding the reload or by using the low-level interface <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> in combination with driver monitors (see below).</p> </dd> <dt><strong><strong>load_driver/2 and reload_driver/2</strong></strong></dt> <dd> <p>This pair of functions are used when open ports towards the driver should be killed with reason <span class="code">driver_unloaded</span> to allow for new driver code to get loaded.</p> <p>If, however, another process has the driver loaded, calling <span class="code">reload_driver</span> returns the error code <span class="code">pending_process</span>. As stated earlier, the recommended design is to not allow other <span class="bold_code"><a href="#users">users</a></span> than the "driver reloader" to actually demand loading of the concerned driver.</p> </dd> </dl> </dd> </dl> </p></div> <h3>DATA TYPES</h3> <p> <span class="bold_code"><a name="type-driver">driver()</a> = string() | atom()</span><br></p> <p> <span class="bold_code"><a name="type-path">path()</a> = string() | atom()</span><br></p> <h3>EXPORTS</h3> <p><a name="demonitor-1"><span class="bold_code">demonitor(MonitorRef) -> ok</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">MonitorRef = reference()</span><br> </div> </div> <div class="REFBODY"><p> <p>Removes a driver monitor in much the same way as <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','erts','erlang.html#erlang:demonitor-1');">erlang:demonitor/1</a></span> does with process monitors. See <span class="bold_code"><a href="#monitor-2">monitor/2</a></span>, <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> and <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span> for details about how to create driver monitors.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameter is not a reference(). </p> </p></div> <p><a name="info-0"></a><span class="bold_code">info() -> AllInfoList</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">AllInfoList = [DriverInfo]</span></div> <div class="REFTYPES"><span class="bold_code">DriverInfo = {DriverName, InfoList}</span></div> <div class="REFTYPES"><span class="bold_code">DriverName = string()</span></div> <div class="REFTYPES"><span class="bold_code">InfoList = [InfoItem]</span></div> <div class="REFTYPES"><span class="bold_code">InfoItem = {Tag :: atom(), Value :: term()}</span></div> </div></p> <div class="REFBODY"><p> <p>Returns a list of tuples <span class="code">{DriverName, InfoList}</span>, where <span class="code">InfoList</span> is the result of calling <span class="bold_code"><a href="#info-1">info/1</a></span> for that <span class="code">DriverName</span>. Only dynamically linked in drivers are included in the list.</p> </p></div> <p><a name="info-1"></a><span class="bold_code">info(Name) -> InfoList</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">InfoList = [InfoItem, ...]</span></div> <div class="REFTYPES"><span class="bold_code">InfoItem = {Tag :: atom(), Value :: term()}</span></div> </div></p> <div class="REFBODY"><p> <p>Returns a list of tuples <span class="code">{Tag, Value}</span>, where <span class="code">Tag</span> is the information item and <span class="code">Value</span> is the result of calling <span class="bold_code"><a href="#info-2">info/2</a></span> with this driver name and this tag. The result being a tuple list containing all information available about a driver. </p> <p>The different tags that will appear in the list are:</p> <ul> <li>processes</li> <li>driver_options</li> <li>port_count</li> <li>linked_in_driver</li> <li>permanent</li> <li>awaiting_load</li> <li>awaiting_unload</li> </ul> <p>For a detailed description of each value, please read the description of <span class="bold_code"><a href="#info-2">info/2</a></span> below.</p> <p>The function throws a <span class="code">badarg</span> exception if the driver is not present in the system.</p> </p></div> <p><a name="info-2"><span class="bold_code">info(Name, Tag) -> Value</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">Name = string() | atom()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Tag = processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Value = term()</span><br> </div> </div> <div class="REFBODY"><p> <p>This function returns specific information about one aspect of a driver. The <span class="code">Tag</span> parameter specifies which aspect to get information about. The <span class="code">Value</span> return differs between different tags:</p> <dl> <dt><strong><strong>processes</strong></strong></dt> <dd> <p>Return all processes containing <span class="bold_code"><a href="#users">users</a></span> of the specific drivers as a list of tuples <span class="code">{pid(),int()}</span>, where the <span class="code">int()</span> denotes the number of users in the process <span class="code">pid()</span>.</p> </dd> <dt><strong><strong>driver_options</strong></strong></dt> <dd> <p>Return a list of the driver options provided when loading, as well as any options set by the driver itself during initialization. The currently only valid option being <span class="code">kill_ports</span>.</p> </dd> <dt><strong><strong>port_count</strong></strong></dt> <dd> <p>Return the number of ports (an <span class="code">int()</span>) using the driver.</p> </dd> <dt><strong><strong>linked_in_driver</strong></strong></dt> <dd> <p>Return a <span class="code">bool()</span>, being <span class="code">true</span> if the driver is a statically linked in one and <span class="code">false</span> otherwise.</p> </dd> <dt><strong><strong>permanent</strong></strong></dt> <dd> <p>Return a <span class="code">bool()</span>, being <span class="code">true</span> if the driver has made itself permanent (and is <strong>not</strong> a statically linked in driver). <span class="code">false</span> otherwise.</p> </dd> <dt><strong><strong>awaiting_load</strong></strong></dt> <dd> <p>Return a list of all processes having monitors for <span class="code">loading</span> active, each process returned as <span class="code">{pid(),int()}</span>, where the <span class="code">int()</span> is the number of monitors held by the process <span class="code">pid()</span>.</p> </dd> <dt><strong><strong>awaiting_unload</strong></strong></dt> <dd> <p>Return a list of all processes having monitors for <span class="code">unloading</span> active, each process returned as <span class="code">{pid(),int()}</span>, where the <span class="code">int()</span> is the number of monitors held by the process <span class="code">pid()</span>.</p> </dd> </dl> <p>If the options <span class="code">linked_in_driver</span> or <span class="code">permanent</span> return true, all other options will return the value <span class="code">linked_in_driver</span> or <span class="code">permanent</span> respectively.</p> <p>The function throws a <span class="code">badarg</span> exception if the driver is not present in the system or the tag is not supported.</p> </p></div> <p><a name="load-2"></a><span class="bold_code">load(Path, Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Path = <span class="bold_code"><a href="#type-path">path()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Loads and links the dynamic driver <span class="code">Name</span>. <span class="code">Path</span> is a file path to the directory containing the driver. <span class="code">Name</span> must be a sharable object/dynamic library. Two drivers with different <span class="code">Path</span> parameters cannot be loaded under the same name. The <span class="code">Name</span> is a string or atom containing at least one character.</p> <p>The <span class="code">Name</span> given should correspond to the filename of the actual dynamically loadable object file residing in the directory given as <span class="code">Path</span>, but <strong>without</strong> the extension (i.e. <span class="code">.so</span>). The driver name provided in the driver initialization routine must correspond with the filename, in much the same way as erlang module names correspond to the names of the <span class="code">.beam</span> files.</p> <p>If the driver has been previously unloaded, but is still present due to open ports against it, a call to <span class="code">load/2</span> will stop the unloading and keep the driver (as long as the <span class="code">Path</span> is the same) and <span class="code">ok</span> is returned. If one actually wants the object code to be reloaded, one uses <span class="bold_code"><a href="#reload-2">reload/2</a></span> or the low-level interface <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> instead. Please refer to the description of <span class="bold_code"><a href="#scenarios">different scenarios</a></span> for loading/unloading in the introduction.</p> <p>If more than one process tries to load an already loaded driver withe the same <span class="code">Path</span>, or if the same process tries to load it several times, the function will return <span class="code">ok</span>. The emulator will keep track of the <span class="code">load/2</span> calls, so that a corresponding number of <span class="code">unload/2</span> calls will have to be done from the same process before the driver will actually get unloaded. It is therefore safe for an application to load a driver that is shared between processes or applications when needed. It can safely be unloaded without causing trouble for other parts of the system. </p> <p>It is not allowed to load several drivers with the same name but with different <span class="code">Path</span> parameters.</p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>Note especially that the <span class="code">Path</span> is interpreted literally, so that all loaders of the same driver needs to give the same <strong>literal</strong><span class="code">Path</span> string, even though different paths might point out the same directory in the filesystem (due to use of relative paths and links).</p> </p></div> </div> <p>On success, the function returns <span class="code">ok</span>. On failure, the return value is <span class="code">{error,ErrorDesc}</span>, where <span class="code">ErrorDesc</span> is an opaque term to be translated into human readable form by the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function.</p> <p>For more control over the error handling, again use the <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> interface instead.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="load_driver-2"></a><span class="bold_code">load_driver(Path, Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Path = <span class="bold_code"><a href="#type-path">path()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Works essentially as <span class="code">load/2</span>, but will load the driver with other options. All ports that are using the driver will get killed with the reason <span class="code">driver_unloaded</span> when the driver is to be unloaded.</p> <p>The number of loads and unloads by different <span class="bold_code"><a href="#users">users</a></span> influence the actual loading and unloading of a driver file. The port killing will therefore only happen when the <strong>last</strong> <span class="bold_code"><a href="#users">user</a></span> unloads the driver, or the last process having loaded the driver exits.</p> <p>This interface (or at least the name of the functions) is kept for backward compatibility. Using <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> with <span class="code">{driver_options,[kill_ports]} </span> in the option list will give the same effect regarding the port killing.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="monitor-2"><span class="bold_code">monitor(Tag, Item) -> MonitorRef</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">Tag = driver </span><br> </div> <div class="REFTYPES"> <span class="bold_code">Item = {Name, When}</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Name = atom() | string()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">When = loaded | unloaded | unloaded_only</span><br> </div> <div class="REFTYPES"> <span class="bold_code">MonitorRef = reference()</span><br> </div> </div> <div class="REFBODY"><p> <p>This function creates a driver monitor and works in many ways as the function <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','erts','erlang.html#erlang:monitor-2');">erlang:monitor/2</a></span>, does for processes. When a driver changes state, the monitor results in a monitor-message being sent to the calling process. The <span class="code">MonitorRef</span> returned by this function is included in the message sent.</p> <p>As with process monitors, each driver monitor set will only generate <strong>one single message</strong>. The monitor is "destroyed" after the message is sent and there is then no need to call <span class="bold_code"><a href="#demonitor-1">demonitor/1</a></span>.</p> <p>The <span class="code">MonitorRef</span> can also be used in subsequent calls to <span class="bold_code"><a href="#demonitor-1">demonitor/1</a></span> to remove a monitor.</p> <p>The function accepts the following parameters:</p> <dl> <dt><strong><strong>Tag</strong></strong></dt> <dd> <p>The monitor tag is always <span class="code">driver</span> as this function can only be used to create driver monitors. In the future, driver monitors will be integrated with process monitors, why this parameter has to be given for consistence.</p> </dd> <dt><strong><strong>Item</strong></strong></dt> <dd> <p>The <span class="code">Item</span> parameter specifies which driver one wants to monitor (the name of the driver) as well as which state change one wants to monitor. The parameter is a tuple of arity two whose first element is the driver name and second element is either of:</p> <dl> <dt><strong><strong>loaded</strong></strong></dt> <dd> <p>Notify me when the driver is reloaded (or loaded if loading is underway). It only makes sense to monitor drivers that are in the process of being loaded or reloaded. One cannot monitor a future-to-be driver name for loading, that will only result in a <span class="code">'DOWN'</span> message being immediately sent. Monitoring for loading is therefore most useful when triggered by the <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> function, where the monitor is created <strong>because</strong> the driver is in such a pending state.</p> <p>Setting a driver monitor for <span class="code">loading</span> will eventually lead to one of the following messages being sent:</p> <dl> <dt><strong><strong>{'UP', reference(), driver, Name, loaded}</strong></strong></dt> <dd> <p>This message is sent, either immediately if the driver is already loaded and no reloading is pending, or when reloading is executed if reloading is pending. </p> <p>The <span class="bold_code"><a href="#users">user</a></span> is expected to know if reloading is demanded prior to creating a monitor for loading.</p> </dd> <dt><strong><strong>{'UP', reference(), driver, Name, permanent}</strong></strong></dt> <dd> <p>This message will be sent if reloading was expected, but the (old) driver made itself permanent prior to reloading. It will also be sent if the driver was permanent or statically linked in when trying to create the monitor.</p> </dd> <dt><strong><strong>{'DOWN', reference(), driver, Name, load_cancelled}</strong></strong></dt> <dd> <p>This message will arrive if reloading was underway, but the <span class="bold_code"><a href="#users">user</a></span> having requested reload cancelled it by either dying or calling <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span> (or <span class="code">unload/1</span>/<span class="code">unload_driver/1</span>) again before it was reloaded.</p> </dd> <dt><strong><strong>{'DOWN', reference(), driver, Name, {load_failure, Failure}}</strong></strong></dt> <dd> <p>This message will arrive if reloading was underway but the loading for some reason failed. The <span class="code">Failure</span> term is one of the errors that can be returned from <span class="bold_code"><a href="#try_load-3">try_load/3</a></span>. The error term can be passed to <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> for translation into human readable form. Note that the translation has to be done in the same running erlang virtual machine as the error was detected in.</p> </dd> </dl> </dd> <dt><strong><strong>unloaded</strong></strong></dt> <dd> <p>Monitor when a driver gets unloaded. If one monitors a driver that is not present in the system, one will immediately get notified that the driver got unloaded. There is no guarantee that the driver was actually ever loaded.</p> <p>A driver monitor for unload will eventually result in one of the following messages being sent:</p> <dl> <dt><strong><strong>{'DOWN', reference(), driver, Name, unloaded}</strong></strong></dt> <dd> <p>The driver instance monitored is now unloaded. As the unload might have been due to a <span class="code">reload/2</span> request, the driver might once again have been loaded when this message arrives.</p> </dd> <dt><strong><strong>{'UP', reference(), driver, Name, unload_cancelled}</strong></strong></dt> <dd> <p>This message will be sent if unloading was expected, but while the driver was waiting for all ports to get closed, a new <span class="bold_code"><a href="#users">user</a></span> of the driver appeared and the unloading was cancelled.</p> <p>This message appears when an <span class="code">{ok, pending_driver}</span>) was returned from <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span>) for the last <span class="bold_code"><a href="#users">user</a></span> of the driver and then a <span class="code">{ok, already_loaded}</span> is returned from a call to <span class="bold_code"><a href="#try_load-3">try_load/3</a></span>.</p> <p>If one wants to <strong>really</strong> monitor when the driver gets unloaded, this message will distort the picture, no unloading was really done. The <span class="code">unloaded_only</span> option creates a monitor similar to an <span class="code">unloaded</span> monitor, but does never result in this message.</p> </dd> <dt><strong><strong>{'UP', reference(), driver, Name, permanent}</strong></strong></dt> <dd> <p>This message will be sent if unloading was expected, but the driver made itself permanent prior to unloading. It will also be sent if trying to monitor a permanent or statically linked in driver.</p> </dd> </dl> </dd> <dt><strong><strong>unloaded_only</strong></strong></dt> <dd> <p>A monitor created as <span class="code">unloaded_only</span> behaves exactly as one created as <span class="code">unloaded</span> with the exception that the <span class="code">{'UP', reference(), driver, Name, unload_cancelled}</span> message will never be sent, but the monitor instead persists until the driver <strong>really</strong> gets unloaded.</p> </dd> </dl> </dd> </dl> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="reload-2"></a><span class="bold_code">reload(Path, Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Path = <span class="bold_code"><a href="#type-path">path()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = pending_process | OpaqueError</span></div> <div class="REFTYPES"><span class="bold_code">OpaqueError = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Reloads the driver named <span class="code">Name</span> from a possibly different <span class="code">Path</span> than was previously used. This function is used in the code change <span class="bold_code"><a href="#scenarios">scenario</a></span> described in the introduction.</p> <p>If there are other <span class="bold_code"><a href="#users">users</a></span> of this driver, the function will return <span class="code">{error, pending_process}</span>, but if there are no more users, the function call will hang until all open ports are closed.</p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>Avoid mixing several <span class="bold_code"><a href="#users">users</a></span> with driver reload requests.</p> </p></div> </div> <p>If one wants to avoid hanging on open ports, one should use the <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> function instead.</p> <p>The <span class="code">Name</span> and <span class="code">Path</span> parameters have exactly the same meaning as when calling the plain <span class="bold_code"><a href="#load-2">load/2</a></span> function.</p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>Avoid mixing several <span class="bold_code"><a href="#users">users</a></span> with driver reload requests.</p> </p></div> </div> <p>On success, the function returns <span class="code">ok</span>. On failure, the function returns an opaque error, with the exception of the <span class="code">pending_process</span> error described above. The opaque errors are to be translated into human readable form by the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function.</p> <p>For more control over the error handling, again use the <span class="bold_code"><a href="#try_load-3">try_load/3</a></span> interface instead.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="reload_driver-2"></a><span class="bold_code">reload_driver(Path, Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Path = <span class="bold_code"><a href="#type-path">path()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = pending_process | OpaqueError</span></div> <div class="REFTYPES"><span class="bold_code">OpaqueError = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Works exactly as <span class="bold_code"><a href="#reload-2">reload/2</a></span>, but for drivers loaded with the <span class="bold_code"><a href="#load_driver-2">load_driver/2</a></span> interface. </p> <p>As this interface implies that ports are being killed when the last user disappears, the function wont hang waiting for ports to get closed.</p> <p>For further details, see the <span class="bold_code"><a href="#scenarios">scenarios</a></span> in the module description and refer to the <span class="bold_code"><a href="#reload-2">reload/2</a></span> function description.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="try_load-3"><span class="bold_code">try_load(Path, Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc}</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">Path = Name = string() | atom()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">OptionList = [ Option ]</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Option = {driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption}</span><br> </div> <div class="REFTYPES"> <span class="bold_code">DriverOptionList = [ DriverOption ]</span><br> </div> <div class="REFTYPES"> <span class="bold_code">DriverOption = kill_ports</span><br> </div> <div class="REFTYPES"> <span class="bold_code">MonitorOption = pending_driver | pending</span><br> </div> <div class="REFTYPES"> <span class="bold_code">ReloadOption = pending_driver | pending</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Status = loaded | already_loaded | PendingStatus </span><br> </div> <div class="REFTYPES"> <span class="bold_code">PendingStatus = pending_driver | pending_process</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Ref = reference()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">ErrorDesc = ErrorAtom | OpaqueError</span><br> </div> <div class="REFTYPES"> <span class="bold_code">ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process</span><br> </div> </div> <div class="REFBODY"><p> <p>This function provides more control than the <span class="code">load/2</span>/<span class="code">reload/2</span> and <span class="code">load_driver/2</span>/<span class="code">reload_driver/2</span> interfaces. It will never wait for completion of other operations related to the driver, but immediately return the status of the driver as either:</p> <dl> <dt><strong><strong>{ok, loaded}</strong></strong></dt> <dd> <p>The driver was actually loaded and is immediately usable.</p> </dd> <dt><strong><strong>{ok, already_loaded}</strong></strong></dt> <dd> <p>The driver was already loaded by another process and/or is in use by a living port. The load by you is registered and a corresponding <span class="code">try_unload</span> is expected sometime in the future.</p> </dd> <dt><strong><strong>{ok, pending_driver}</strong>or <strong>{ok, pending_driver, reference()}</strong></strong></dt> <dd> <p>The load request is registered, but the loading is delayed due to the fact that an earlier instance of the driver is still waiting to get unloaded (there are open ports using it). Still, unload is expected when you are done with the driver. This return value will <strong>mostly</strong> happen when the <span class="code">{reload,pending_driver}</span> or <span class="code">{reload,pending}</span> options are used, but <strong>can</strong> happen when another <span class="bold_code"><a href="#users">user</a></span> is unloading a driver in parallel and the <span class="code">kill_ports</span> driver option is set. In other words, this return value will always need to be handled!</p> </dd> <dt><strong><strong>{ok, pending_process}</strong>or <strong>{ok, pending_process, reference()}</strong></strong></dt> <dd> <p>The load request is registered, but the loading is delayed due to the fact that an earlier instance of the driver is still waiting to get unloaded by another <span class="bold_code"><a href="#users">user</a></span> (not only by a port, in which case <span class="code">{ok,pending_driver}</span> would have been returned). Still, unload is expected when you are done with the driver. This return value will <strong>only</strong> happen when the <span class="code">{reload,pending}</span> option is used.</p> </dd> </dl> <p>When the function returns <span class="code">{ok, pending_driver}</span> or <span class="code">{ok, pending_process}</span>, one might want to get information about when the driver is <strong>actually</strong> loaded. This can be achieved by using the <span class="code">{monitor, PendingOption}</span> option.</p> <p>When monitoring is requested, and a corresponding <span class="code">{ok, pending_driver}</span> or <span class="code">{ok, pending_process}</span> would be returned, the function will instead return a tuple <span class="code">{ok, PendingStatus, reference()}</span> and the process will, at a later time when the driver actually gets loaded, get a monitor message. The monitor message one can expect is described in the <span class="bold_code"><a href="#monitor-2">monitor/2</a></span> function description. </p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>Note that in case of loading, monitoring can <strong>not</strong> only get triggered by using the <span class="code">{reload, ReloadOption}</span> option, but also in special cases where the load-error is transient, why <span class="code">{monitor, pending_driver}</span> should be used under basically <strong>all</strong> real world circumstances!</p> </p></div> </div> <p>The function accepts the following parameters:</p> <dl> <dt><strong><strong>Path</strong></strong></dt> <dd> <p>The filesystem path to the directory where the driver object file is situated. The filename of the object file (minus extension) must correspond to the driver name (used in the name parameter) and the driver must identify itself with the very same name. The <span class="code">Path</span> might be provided as an <strong>io_list</strong>, meaning it can be a list of other io_lists, characters (eight bit integers) or binaries, all to be flattened into a sequence of characters.</p> <p>The (possibly flattened) <span class="code">Path</span> parameter must be consistent throughout the system, a driver should, by all <span class="bold_code"><a href="#users">users</a></span>, be loaded using the same <strong>literal</strong><span class="code">Path</span>. The exception is when <strong>reloading</strong> is requested, in which case the <span class="code">Path</span> may be specified differently. Note that all <span class="bold_code"><a href="#users">users</a></span> trying to load the driver at a later time will need to use the <strong>new</strong><span class="code">Path</span> if the <span class="code">Path</span> is changed using a <span class="code">reload</span> option. This is yet another reason to have <strong>only one loader</strong> of a driver one wants to upgrade in a running system! </p> </dd> <dt><strong><strong>Name</strong></strong></dt> <dd> <p>The name parameter is the name of the driver to be used in subsequent calls to <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','erts','erlang.html#open_port-2');">open_port</a></span>. The name can be specified either as an <span class="code">io_list()</span> or as an <span class="code">atom()</span>. The name given when loading is used to find the actual object file (with the help of the <span class="code">Path</span> and the system implied extension suffix, i.e. <span class="code">.so</span>). The name by which the driver identifies itself must also be consistent with this <span class="code">Name</span> parameter, much as a beam-file's module name much correspond to its filename.</p> </dd> <dt><strong><strong>OptionList</strong></strong></dt> <dd> <p>A number of options can be specified to control the loading operation. The options are given as a list of two-tuples, the tuples having the following values and meanings:</p> <dl> <dt><strong><strong>{driver_options, DriverOptionsList}</strong></strong></dt> <dd> <p>This option is to provide options that will change its general behavior and will "stick" to the driver throughout its lifespan.</p> <p>The driver options for a given driver name need always to be consistent, <strong>even when the driver is reloaded</strong>, meaning that they are as much a part of the driver as the actual name.</p> <p>Currently the only allowed driver option is <span class="code">kill_ports</span>, which means that all ports opened towards the driver are killed with the exit-reason <span class="code">driver_unloaded</span> when no process any longer has the driver loaded. This situation arises either when the last <span class="bold_code"><a href="#users">user</a></span> calls <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span>, or the last process having loaded the driver exits.</p> </dd> <dt><strong><strong>{monitor, MonitorOption}</strong></strong></dt> <dd> <p>A <span class="code">MonitorOption</span> tells <span class="code">try_load/3</span> to trigger a driver monitor under certain conditions. When the monitor is triggered, the function will return a three-tuple <span class="code">{ok, PendingStatus, reference()}</span>, where the <span class="code">reference()</span> is the monitor ref for the driver monitor.</p> <p>Only one <span class="code">MonitorOption</span> can be specified and it is either the atom <span class="code">pending</span>, which means that a monitor should be created whenever a load operation is delayed, and the atom <span class="code">pending_driver</span>, in which a monitor is created whenever the operation is delayed due to open ports towards an otherwise unused driver. The <span class="code">pending_driver</span> option is of little use, but is present for completeness, it is very well defined which reload-options might give rise to which delays. It might, however, be a good idea to use the same <span class="code">MonitorOption</span> as the <span class="code">ReloadOption</span> if present.</p> <p>If reloading is not requested, it might still be useful to specify the <span class="code">monitor</span> option, as forced unloads (<span class="code">kill_ports</span> driver option or the <span class="code">kill_ports</span> option to <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span>) will trigger a transient state where driver loading cannot be performed until all closing ports are actually closed. So, as <span class="code">try_unload</span> can, in almost all situations, return <span class="code">{ok, pending_driver}</span>, one should always specify at least <span class="code">{monitor, pending_driver}</span> in production code (see the monitor discussion above). </p> </dd> <dt><strong><strong>{reload,RealoadOption}</strong></strong></dt> <dd> <p>This option is used when one wants to <strong>reload</strong> a driver from disk, most often in a code upgrade scenario. Having a <span class="code">reload</span> option also implies that the <span class="code">Path</span> parameter need <strong>not</strong> be consistent with earlier loads of the driver.</p> <p>To reload a driver, the process needs to have previously loaded the driver, i.e there has to be an active <span class="bold_code"><a href="#users">user</a></span> of the driver in the process. </p> <p>The <span class="code">reload</span> option can be either the atom <span class="code">pending</span>, in which reloading is requested for any driver and will be effectuated when <strong>all</strong> ports opened against the driver are closed. The replacement of the driver will in this case take place regardless of if there are still pending <span class="bold_code"><a href="#users">users</a></span> having the driver loaded! The option also triggers port-killing (if the <span class="code">kill_ports</span> driver option is used) even though there are pending users, making it usable for forced driver replacement, but laying a lot of responsibility on the driver <span class="bold_code"><a href="#users">users</a></span>. The pending option is seldom used as one does not want other <span class="bold_code"><a href="#users">users</a></span> to have loaded the driver when code change is underway. </p> <p>The more useful option is <span class="code">pending_driver</span>, which means that reloading will be queued if the driver is <strong>not</strong> loaded by any other <span class="bold_code"><a href="#users">users</a></span>, but the driver has opened ports, in which case <span class="code">{ok, pending_driver}</span> will be returned (a <span class="code">monitor</span> option is of course recommended).</p> <p>If the driver is unloaded (not present in the system), the error code <span class="code">not_loaded</span> will be returned. The <span class="code">reload</span> option is intended for when the user has already loaded the driver in advance.</p> </dd> </dl> </dd> </dl> <p>The function might return numerous errors, of which some only can be returned given a certain combination of options.</p> <p>A number of errors are opaque and can only be interpreted by passing them to the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function, but some can be interpreted directly:</p> <dl> <dt><strong><strong>{error,linked_in_driver}</strong></strong></dt> <dd> <p>The driver with the specified name is an erlang statically linked in driver, which cannot be manipulated with this API.</p> </dd> <dt><strong><strong>{error,inconsistent}</strong></strong></dt> <dd> <p>The driver has already been loaded with either other <span class="code">DriverOptions</span> or a different <strong>literal</strong><span class="code">Path</span> argument.</p> <p>This can happen even if a <span class="code">reload</span> option is given, if the <span class="code">DriverOptions</span> differ from the current.</p> </dd> <dt><strong><strong>{error, permanent}</strong></strong></dt> <dd> <p>The driver has requested itself to be permanent, making it behave like an erlang linked in driver and it can no longer be manipulated with this API.</p> </dd> <dt><strong><strong>{error, pending_process}</strong></strong></dt> <dd> <p>The driver is loaded by other <span class="bold_code"><a href="#users">users</a></span> when the <span class="code">{reload, pending_driver}</span> option was given.</p> </dd> <dt><strong><strong>{error, pending_reload}</strong></strong></dt> <dd> <p>Driver reload is already requested by another <span class="bold_code"><a href="#users">user</a></span> when the <span class="code">{reload, ReloadOption}</span> option was given.</p> </dd> <dt><strong><strong>{error, not_loaded_by_this_process}</strong></strong></dt> <dd> <p>Appears when the <span class="code">reload</span> option is given. The driver <span class="code">Name</span> is present in the system, but there is no <span class="bold_code"><a href="#users">user</a></span> of it in this process.</p> </dd> <dt><strong><strong>{error, not_loaded}</strong></strong></dt> <dd> <p>Appears when the <span class="code">reload</span> option is given. The driver <span class="code">Name</span> is not in the system. Only drivers loaded by this process can be reloaded.</p> </dd> </dl> <p>All other error codes are to be translated by the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function. Note that calls to <span class="code">format_error</span> should be performed from the same running instance of the erlang virtual machine as the error was detected in, due to system dependent behavior concerning error values.</p> <p>If the arguments or options are malformed, the function will throw a <span class="code">badarg</span> exception.</p> </p></div> <p><a name="try_unload-2"><span class="bold_code">try_unload(Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom}</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">Name = string() | atom()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">OptionList = [ Option ]</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Option = {monitor, MonitorOption} | kill_ports</span><br> </div> <div class="REFTYPES"> <span class="bold_code">MonitorOption = pending_driver | pending</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Status = unloaded | PendingStatus </span><br> </div> <div class="REFTYPES"> <span class="bold_code">PendingStatus = pending_driver | pending_process</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Ref = reference()</span><br> </div> <div class="REFTYPES"> <span class="bold_code">ErrorAtom = linked_in_driver | not_loaded | not_loaded_by_this_process | permanent</span><br> </div> </div> <div class="REFBODY"><p> <p>This is the low level function to unload (or decrement reference counts of) a driver. It can be used to force port killing, in much the same way as the driver option <span class="code">kill_ports</span> implicitly does, and it can trigger a monitor either due to other <span class="bold_code"><a href="#users">users</a></span> still having the driver loaded or that there are open ports using the driver.</p> <p>Unloading can be described as the process of telling the emulator that this particular part of the code in this particular process (i.e. this <span class="bold_code"><a href="#users">user</a></span>) no longer needs the driver. That can, if there are no other users, trigger actual unloading of the driver, in which case the driver name disappears from the system and (if possible) the memory occupied by the driver executable code is reclaimed. If the driver has the <span class="code">kill_ports</span> option set, or if <span class="code">kill_ports</span> was specified as an option to this function, all pending ports using this driver will get killed when unloading is done by the last <span class="bold_code"><a href="#users">user</a></span>. If no port-killing is involved and there are open ports, the actual unloading is delayed until there are no more open ports using the driver. If, in this case, another <span class="bold_code"><a href="#users">user</a></span> (or even this user) loads the driver again before the driver is actually unloaded, the unloading will never take place.</p> <p>To allow the <span class="bold_code"><a href="#users">user</a></span> that <strong>requests unloading</strong> to wait for <strong>actual unloading</strong> to take place, <span class="code">monitor</span> triggers can be specified in much the same way as when loading. As <span class="bold_code"><a href="#users">users</a></span> of this function however seldom are interested in more than decrementing the reference counts, monitoring is more seldom needed. If the <span class="code">kill_ports</span> option is used however, monitor trigging is crucial, as the ports are not guaranteed to have been killed until the driver is unloaded, why a monitor should be triggered for at least the <span class="code">pending_driver</span> case.</p> <p>The possible monitor messages that can be expected are the same as when using the <span class="code">unloaded</span> option to the <span class="bold_code"><a href="#monitor-2">monitor/2</a></span> function.</p> <p>The function will return one of the following statuses upon success:</p> <dl> <dt><strong><strong>{ok, unloaded}</strong></strong></dt> <dd> <p>The driver was immediately unloaded, meaning that the driver name is now free to use by other drivers and, if the underlying OS permits it, the memory occupied by the driver object code is now reclaimed.</p> <p>The driver can only be unloaded when there are no open ports using it and there are no more <span class="bold_code"><a href="#users">users</a></span> requiring it to be loaded.</p> </dd> <dt><strong><strong>{ok, pending_driver}</strong>or <strong>{ok, pending_driver, reference()}</strong></strong></dt> <dd> <p>This return value indicates that this call removed the last <span class="bold_code"><a href="#users">user</a></span> from the driver, but there are still open ports using it. When all ports are closed and no new <span class="bold_code"><a href="#users">users</a></span> have arrived, the driver will actually be reloaded and the name and memory reclaimed.</p> <p>This return value is valid even when the option <span class="code">kill_ports</span> was used, as killing ports may not be a process that completes immediately. The condition is, in that case, however transient. Monitors are as always useful to detect when the driver is really unloaded.</p> </dd> <dt><strong><strong>{ok, pending_process}</strong>or <strong>{ok, pending_process, reference()}</strong></strong></dt> <dd> <p>The unload request is registered, but there are still other <span class="bold_code"><a href="#users">users</a></span> holding the driver. Note that the term <span class="code">pending_process</span> might refer to the running process, there might be more than one <span class="bold_code"><a href="#users">user</a></span> in the same process.</p> <p>This is a normal, healthy return value if the call was just placed to inform the emulator that you have no further use of the driver. It is actually the most common return value in the most common <span class="bold_code"><a href="#scenarios">scenario</a></span> described in the introduction.</p> </dd> </dl> <p>The function accepts the following parameters:</p> <dl> <dt><strong><strong>Name</strong></strong></dt> <dd> <p>The name parameter is the name of the driver to be unloaded. The name can be specified either as an <span class="code">io_list()</span> or as an <span class="code">atom()</span>. </p> </dd> <dt><strong><strong>OptionList</strong></strong></dt> <dd> <p>The <span class="code">OptionList</span> argument can be used to specify certain behavior regarding ports as well as triggering monitors under certain conditions:</p> <dl> <dt><strong><strong>kill_ports</strong></strong></dt> <dd> <p>Force killing of all ports opened using this driver, with the exit reason <span class="code">driver_unloaded</span>, if you are the <strong>last</strong><span class="bold_code"><a href="#users">user</a></span> of the driver.</p> <p>If there are other <span class="bold_code"><a href="#users">users</a></span> having the driver loaded, this option will have no effect.</p> <p>If one wants the consistent behavior of killing ports when the last <span class="bold_code"><a href="#users">user</a></span> unloads, one should use the driver option <span class="code">kill_ports</span> when loading the driver instead.</p> </dd> <dt><strong><strong>{monitor, MonitorOption}</strong></strong></dt> <dd> <p>This option creates a driver monitor if the condition given in <span class="code">MonitorOptions</span> is true. The valid options are:</p> <dl> <dt><strong><strong>pending_driver</strong></strong></dt> <dd> <p>Create a driver monitor if the return value is to be <span class="code">{ok, pending_driver}</span>.</p> </dd> <dt><strong><strong>pending</strong></strong></dt> <dd> <p>Create a monitor if the return value will be either <span class="code">{ok, pending_driver}</span> or <span class="code">{ok, pending_process}</span>.</p> </dd> </dl> <p>The <span class="code">pending_driver</span> <span class="code">MonitorOption</span> is by far the most useful and it has to be used to ensure that the driver has really been unloaded and the ports closed whenever the <span class="code">kill_ports</span> option is used or the driver may have been loaded with the <span class="code">kill_ports</span> driver option.</p> <p>By using the monitor-triggers in the call to <span class="code">try_unload</span> one can be sure that the monitor is actually added before the unloading is executed, meaning that the monitor will always get properly triggered, which would not be the case if one called <span class="code">erl_ddll:monitor/2</span> separately.</p> </dd> </dl> </dd> </dl> <p>The function may return several error conditions, of which all are well specified (no opaque values):</p> <dl> <dt><strong><strong>{error, linked_in_driver}</strong></strong></dt> <dd> <p>You were trying to unload an erlang statically linked in driver, which cannot be manipulated with this interface (and cannot be unloaded at all).</p> </dd> <dt><strong><strong>{error, not_loaded}</strong></strong></dt> <dd> <p>The driver <span class="code">Name</span> is not present in the system.</p> </dd> <dt><strong><strong>{error, not_loaded_by_this_process}</strong></strong></dt> <dd> <p>The driver <span class="code">Name</span> is present in the system, but there is no <span class="bold_code"><a href="#users">user</a></span> of it in this process. </p> <p>As a special case, drivers can be unloaded from processes that has done no corresponding call to <span class="code">try_load/3</span> if, and only if, there are <strong>no users of the driver at all</strong>, which may happen if the process containing the last user dies.</p> </dd> <dt><strong><strong>{error, permanent}</strong></strong></dt> <dd> <p>The driver has made itself permanent, in which case it can no longer be manipulated by this interface (much like a statically linked in driver).</p> </dd> </dl> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="unload-1"></a><span class="bold_code">unload(Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Unloads, or at least dereferences the driver named <span class="code">Name</span>. If the caller is the last <span class="bold_code"><a href="#users">user</a></span> of the driver, and there are no more open ports using the driver, the driver will actually get unloaded. In all other cases, actual unloading will be delayed until all ports are closed and there are no remaining <span class="bold_code"><a href="#users">users</a></span>.</p> <p>If there are other <span class="bold_code"><a href="#users">users</a></span> of the driver, the reference counts of the driver is merely decreased, so that the caller is no longer considered a user of the driver. For usage scenarios, see the <span class="bold_code"><a href="#scenarios">description</a></span> in the beginning of this document. </p> <p>The <span class="code">ErrorDesc</span> returned is an opaque value to be passed further on to the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function. For more control over the operation, use the <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span> interface.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="unload_driver-1"></a><span class="bold_code">unload_driver(Name) -> ok | {error, ErrorDesc}</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">Name = <span class="bold_code"><a href="#type-driver">driver()</a></span></span></div> <div class="REFTYPES"><span class="bold_code">ErrorDesc = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Unloads, or at least dereferences the driver named <span class="code">Name</span>. If the caller is the last <span class="bold_code"><a href="#users">user</a></span> of the driver, all remaining open ports using the driver will get killed with the reason <span class="code">driver_unloaded</span> and the driver will eventually get unloaded.</p> <p>If there are other <span class="bold_code"><a href="#users">users</a></span> of the driver, the reference counts of the driver is merely decreased, so that the caller is no longer considered a <span class="bold_code"><a href="#users">user</a></span>. For usage scenarios, see the <span class="bold_code"><a href="#scenarios">description</a></span> in the beginning of this document.</p> <p>The <span class="code">ErrorDesc</span> returned is an opaque value to be passed further on to the <span class="bold_code"><a href="#format_error-1">format_error/1</a></span> function. For more control over the operation, use the <span class="bold_code"><a href="#try_unload-2">try_unload/2</a></span> interface.</p> <p>The function throws a <span class="code">badarg</span> exception if the parameters are not given as described above. </p> </p></div> <p><a name="loaded_drivers-0"><span class="bold_code">loaded_drivers() -> {ok, Drivers}</span></a><br></p> <div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"> <span class="bold_code">Drivers = [Driver]</span><br> </div> <div class="REFTYPES"> <span class="bold_code">Driver = string()</span><br> </div> </div> <div class="REFBODY"><p> <p>Returns a list of all the available drivers, both (statically) linked-in and dynamically loaded ones.</p> <p>The driver names are returned as a list of strings rather than a list of atoms for historical reasons.</p> <p>More information about drivers can be obtained using one of the <span class="bold_code"><a href="#info-0">info</a></span> functions.</p> </p></div> <p><a name="format_error-1"></a><span class="bold_code">format_error(ErrorDesc) -> string()</span><br><div class="REFBODY"> <p>Types:</p> <div class="REFTYPES"><span class="bold_code">ErrorDesc = term()</span></div> </div></p> <div class="REFBODY"><p> <p>Takes an <span class="code">ErrorDesc</span> returned by load, unload or reload functions and returns a string which describes the error or warning.</p> <div class="note"> <div class="label">Note</div> <div class="content"><p> <p>Due to peculiarities in the dynamic loading interfaces on different platform, the returned string is only guaranteed to describe the correct error <strong>if format_error/1 is called in the same instance of the erlang virtual machine as the error appeared in</strong> (meaning the same operating system process)!</p> </p></div> </div> </p></div> <h3><a name="id111369">SEE ALSO</a></h3> <div class="REFBODY"> <p>erl_driver(4), driver_entry(4)</p> </div> </div> <div class="footer"> <hr> <p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>