<!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_driver</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="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/erts-5.9.3.1.pdf">PDF</a><br><a href="../../../doc/index.html">Top</a></small><p><strong>Erlang Run-Time System Application (ERTS)</strong><br><strong>Reference Manual</strong><br><small>Version 5.9.3.1</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 id="no" title="erl_prim_loader " expanded="false">erl_prim_loader<ul>
<li><a href="erl_prim_loader.html">
Top of manual page
</a></li>
<li title="start-3"><a href="erl_prim_loader.html#start-3">start/3</a></li>
<li title="get_file-1"><a href="erl_prim_loader.html#get_file-1">get_file/1</a></li>
<li title="get_path-0"><a href="erl_prim_loader.html#get_path-0">get_path/0</a></li>
<li title="list_dir-1"><a href="erl_prim_loader.html#list_dir-1">list_dir/1</a></li>
<li title="read_file_info-1"><a href="erl_prim_loader.html#read_file_info-1">read_file_info/1</a></li>
<li title="set_path-1"><a href="erl_prim_loader.html#set_path-1">set_path/1</a></li>
</ul>
</li>
<li id="no" title="erlang " expanded="false">erlang<ul>
<li><a href="erlang.html">
Top of manual page
</a></li>
<li title="abs-1"><a href="erlang.html#abs-1">abs/1</a></li>
<li title="adler32-1"><a href="erlang.html#adler32-1">adler32/1</a></li>
<li title="adler32-2"><a href="erlang.html#adler32-2">adler32/2</a></li>
<li title="adler32_combine-3"><a href="erlang.html#adler32_combine-3">adler32_combine/3</a></li>
<li title="append_element-2"><a href="erlang.html#append_element-2">append_element/2</a></li>
<li title="apply-2"><a href="erlang.html#apply-2">apply/2</a></li>
<li title="apply-3"><a href="erlang.html#apply-3">apply/3</a></li>
<li title="atom_to_binary-2"><a href="erlang.html#atom_to_binary-2">atom_to_binary/2</a></li>
<li title="atom_to_list-1"><a href="erlang.html#atom_to_list-1">atom_to_list/1</a></li>
<li title="binary_part-2"><a href="erlang.html#binary_part-2">binary_part/2</a></li>
<li title="binary_part-3"><a href="erlang.html#binary_part-3">binary_part/3</a></li>
<li title="binary_to_atom-2"><a href="erlang.html#binary_to_atom-2">binary_to_atom/2</a></li>
<li title="binary_to_existing_atom-2"><a href="erlang.html#binary_to_existing_atom-2">binary_to_existing_atom/2</a></li>
<li title="binary_to_list-1"><a href="erlang.html#binary_to_list-1">binary_to_list/1</a></li>
<li title="binary_to_list-3"><a href="erlang.html#binary_to_list-3">binary_to_list/3</a></li>
<li title="bitstring_to_list-1"><a href="erlang.html#bitstring_to_list-1">bitstring_to_list/1</a></li>
<li title="binary_to_term-1"><a href="erlang.html#binary_to_term-1">binary_to_term/1</a></li>
<li title="binary_to_term-2"><a href="erlang.html#binary_to_term-2">binary_to_term/2</a></li>
<li title="bit_size-1"><a href="erlang.html#bit_size-1">bit_size/1</a></li>
<li title="bump_reductions-1"><a href="erlang.html#bump_reductions-1">bump_reductions/1</a></li>
<li title="byte_size-1"><a href="erlang.html#byte_size-1">byte_size/1</a></li>
<li title="cancel_timer-1"><a href="erlang.html#cancel_timer-1">cancel_timer/1</a></li>
<li title="check_old_code-1"><a href="erlang.html#check_old_code-1">check_old_code/1</a></li>
<li title="check_process_code-2"><a href="erlang.html#check_process_code-2">check_process_code/2</a></li>
<li title="crc32-1"><a href="erlang.html#crc32-1">crc32/1</a></li>
<li title="crc32-2"><a href="erlang.html#crc32-2">crc32/2</a></li>
<li title="crc32_combine-3"><a href="erlang.html#crc32_combine-3">crc32_combine/3</a></li>
<li title="date-0"><a href="erlang.html#date-0">date/0</a></li>
<li title="decode_packet-3"><a href="erlang.html#decode_packet-3">decode_packet/3</a></li>
<li title="delete_module-1"><a href="erlang.html#delete_module-1">delete_module/1</a></li>
<li title="demonitor-1"><a href="erlang.html#demonitor-1">demonitor/1</a></li>
<li title="demonitor-2"><a href="erlang.html#demonitor-2">demonitor/2</a></li>
<li title="disconnect_node-1"><a href="erlang.html#disconnect_node-1">disconnect_node/1</a></li>
<li title="display-1"><a href="erlang.html#display-1">display/1</a></li>
<li title="element-2"><a href="erlang.html#element-2">element/2</a></li>
<li title="erase-0"><a href="erlang.html#erase-0">erase/0</a></li>
<li title="erase-1"><a href="erlang.html#erase-1">erase/1</a></li>
<li title="error-1"><a href="erlang.html#error-1">error/1</a></li>
<li title="error-2"><a href="erlang.html#error-2">error/2</a></li>
<li title="exit-1"><a href="erlang.html#exit-1">exit/1</a></li>
<li title="exit-2"><a href="erlang.html#exit-2">exit/2</a></li>
<li title="external_size-1"><a href="erlang.html#external_size-1">external_size/1</a></li>
<li title="external_size-2"><a href="erlang.html#external_size-2">external_size/2</a></li>
<li title="float-1"><a href="erlang.html#float-1">float/1</a></li>
<li title="float_to_list-1"><a href="erlang.html#float_to_list-1">float_to_list/1</a></li>
<li title="fun_info-1"><a href="erlang.html#fun_info-1">fun_info/1</a></li>
<li title="fun_info-2"><a href="erlang.html#fun_info-2">fun_info/2</a></li>
<li title="fun_to_list-1"><a href="erlang.html#fun_to_list-1">fun_to_list/1</a></li>
<li title="function_exported-3"><a href="erlang.html#function_exported-3">function_exported/3</a></li>
<li title="garbage_collect-0"><a href="erlang.html#garbage_collect-0">garbage_collect/0</a></li>
<li title="garbage_collect-1"><a href="erlang.html#garbage_collect-1">garbage_collect/1</a></li>
<li title="get-0"><a href="erlang.html#get-0">get/0</a></li>
<li title="get-1"><a href="erlang.html#get-1">get/1</a></li>
<li title="get_cookie-0"><a href="erlang.html#get_cookie-0">get_cookie/0</a></li>
<li title="get_keys-1"><a href="erlang.html#get_keys-1">get_keys/1</a></li>
<li title="get_stacktrace-0"><a href="erlang.html#get_stacktrace-0">get_stacktrace/0</a></li>
<li title="group_leader-0"><a href="erlang.html#group_leader-0">group_leader/0</a></li>
<li title="group_leader-2"><a href="erlang.html#group_leader-2">group_leader/2</a></li>
<li title="halt-0"><a href="erlang.html#halt-0">halt/0</a></li>
<li title="halt-1"><a href="erlang.html#halt-1">halt/1</a></li>
<li title="halt-2"><a href="erlang.html#halt-2">halt/2</a></li>
<li title="hash-2"><a href="erlang.html#hash-2">hash/2</a></li>
<li title="hd-1"><a href="erlang.html#hd-1">hd/1</a></li>
<li title="hibernate-3"><a href="erlang.html#hibernate-3">hibernate/3</a></li>
<li title="integer_to_list-1"><a href="erlang.html#integer_to_list-1">integer_to_list/1</a></li>
<li title="integer_to_list-2"><a href="erlang.html#integer_to_list-2">integer_to_list/2</a></li>
<li title="iolist_to_binary-1"><a href="erlang.html#iolist_to_binary-1">iolist_to_binary/1</a></li>
<li title="iolist_size-1"><a href="erlang.html#iolist_size-1">iolist_size/1</a></li>
<li title="is_alive-0"><a href="erlang.html#is_alive-0">is_alive/0</a></li>
<li title="is_atom-1"><a href="erlang.html#is_atom-1">is_atom/1</a></li>
<li title="is_binary-1"><a href="erlang.html#is_binary-1">is_binary/1</a></li>
<li title="is_bitstring-1"><a href="erlang.html#is_bitstring-1">is_bitstring/1</a></li>
<li title="is_boolean-1"><a href="erlang.html#is_boolean-1">is_boolean/1</a></li>
<li title="is_builtin-3"><a href="erlang.html#is_builtin-3">is_builtin/3</a></li>
<li title="is_float-1"><a href="erlang.html#is_float-1">is_float/1</a></li>
<li title="is_function-1"><a href="erlang.html#is_function-1">is_function/1</a></li>
<li title="is_function-2"><a href="erlang.html#is_function-2">is_function/2</a></li>
<li title="is_integer-1"><a href="erlang.html#is_integer-1">is_integer/1</a></li>
<li title="is_list-1"><a href="erlang.html#is_list-1">is_list/1</a></li>
<li title="is_number-1"><a href="erlang.html#is_number-1">is_number/1</a></li>
<li title="is_pid-1"><a href="erlang.html#is_pid-1">is_pid/1</a></li>
<li title="is_port-1"><a href="erlang.html#is_port-1">is_port/1</a></li>
<li title="is_process_alive-1"><a href="erlang.html#is_process_alive-1">is_process_alive/1</a></li>
<li title="is_record-2"><a href="erlang.html#is_record-2">is_record/2</a></li>
<li title="is_record-3"><a href="erlang.html#is_record-3">is_record/3</a></li>
<li title="is_reference-1"><a href="erlang.html#is_reference-1">is_reference/1</a></li>
<li title="is_tuple-1"><a href="erlang.html#is_tuple-1">is_tuple/1</a></li>
<li title="length-1"><a href="erlang.html#length-1">length/1</a></li>
<li title="link-1"><a href="erlang.html#link-1">link/1</a></li>
<li title="list_to_atom-1"><a href="erlang.html#list_to_atom-1">list_to_atom/1</a></li>
<li title="list_to_binary-1"><a href="erlang.html#list_to_binary-1">list_to_binary/1</a></li>
<li title="list_to_bitstring-1"><a href="erlang.html#list_to_bitstring-1">list_to_bitstring/1</a></li>
<li title="list_to_existing_atom-1"><a href="erlang.html#list_to_existing_atom-1">list_to_existing_atom/1</a></li>
<li title="list_to_float-1"><a href="erlang.html#list_to_float-1">list_to_float/1</a></li>
<li title="list_to_integer-1"><a href="erlang.html#list_to_integer-1">list_to_integer/1</a></li>
<li title="list_to_integer-2"><a href="erlang.html#list_to_integer-2">list_to_integer/2</a></li>
<li title="list_to_pid-1"><a href="erlang.html#list_to_pid-1">list_to_pid/1</a></li>
<li title="list_to_tuple-1"><a href="erlang.html#list_to_tuple-1">list_to_tuple/1</a></li>
<li title="load_module-2"><a href="erlang.html#load_module-2">load_module/2</a></li>
<li title="load_nif-2"><a href="erlang.html#load_nif-2">load_nif/2</a></li>
<li title="loaded-0"><a href="erlang.html#loaded-0">loaded/0</a></li>
<li title="localtime-0"><a href="erlang.html#localtime-0">localtime/0</a></li>
<li title="localtime_to_universaltime-1"><a href="erlang.html#localtime_to_universaltime-1">localtime_to_universaltime/1</a></li>
<li title="localtime_to_universaltime-2"><a href="erlang.html#localtime_to_universaltime-2">localtime_to_universaltime/2</a></li>
<li title="make_ref-0"><a href="erlang.html#make_ref-0">make_ref/0</a></li>
<li title="make_tuple-2"><a href="erlang.html#make_tuple-2">make_tuple/2</a></li>
<li title="make_tuple-3"><a href="erlang.html#make_tuple-3">make_tuple/3</a></li>
<li title="max-2"><a href="erlang.html#max-2">max/2</a></li>
<li title="md5-1"><a href="erlang.html#md5-1">md5/1</a></li>
<li title="md5_final-1"><a href="erlang.html#md5_final-1">md5_final/1</a></li>
<li title="md5_init-0"><a href="erlang.html#md5_init-0">md5_init/0</a></li>
<li title="md5_update-2"><a href="erlang.html#md5_update-2">md5_update/2</a></li>
<li title="memory-0"><a href="erlang.html#memory-0">memory/0</a></li>
<li title="memory-1"><a href="erlang.html#memory-1">memory/1</a></li>
<li title="min-2"><a href="erlang.html#min-2">min/2</a></li>
<li title="module_loaded-1"><a href="erlang.html#module_loaded-1">module_loaded/1</a></li>
<li title="monitor-2"><a href="erlang.html#monitor-2">monitor/2</a></li>
<li title="monitor_node-2"><a href="erlang.html#monitor_node-2">monitor_node/2</a></li>
<li title="monitor_node-3"><a href="erlang.html#monitor_node-3">monitor_node/3</a></li>
<li title="nif_error-1"><a href="erlang.html#nif_error-1">nif_error/1</a></li>
<li title="nif_error-2"><a href="erlang.html#nif_error-2">nif_error/2</a></li>
<li title="node-0"><a href="erlang.html#node-0">node/0</a></li>
<li title="node-1"><a href="erlang.html#node-1">node/1</a></li>
<li title="nodes-0"><a href="erlang.html#nodes-0">nodes/0</a></li>
<li title="nodes-1"><a href="erlang.html#nodes-1">nodes/1</a></li>
<li title="now-0"><a href="erlang.html#now-0">now/0</a></li>
<li title="open_port-2"><a href="erlang.html#open_port-2">open_port/2</a></li>
<li title="phash-2"><a href="erlang.html#phash-2">phash/2</a></li>
<li title="phash2-1"><a href="erlang.html#phash2-1">phash2/1</a></li>
<li title="pid_to_list-1"><a href="erlang.html#pid_to_list-1">pid_to_list/1</a></li>
<li title="port_close-1"><a href="erlang.html#port_close-1">port_close/1</a></li>
<li title="port_command-2"><a href="erlang.html#port_command-2">port_command/2</a></li>
<li title="port_command-3"><a href="erlang.html#port_command-3">port_command/3</a></li>
<li title="port_connect-2"><a href="erlang.html#port_connect-2">port_connect/2</a></li>
<li title="port_control-3"><a href="erlang.html#port_control-3">port_control/3</a></li>
<li title="port_call-3"><a href="erlang.html#port_call-3">port_call/3</a></li>
<li title="port_info-1"><a href="erlang.html#port_info-1">port_info/1</a></li>
<li title="port_info-2"><a href="erlang.html#port_info-2">port_info/2</a></li>
<li title="port_to_list-1"><a href="erlang.html#port_to_list-1">port_to_list/1</a></li>
<li title="ports-0"><a href="erlang.html#ports-0">ports/0</a></li>
<li title="pre_loaded-0"><a href="erlang.html#pre_loaded-0">pre_loaded/0</a></li>
<li title="process_display-2"><a href="erlang.html#process_display-2">process_display/2</a></li>
<li title="process_flag-2"><a href="erlang.html#process_flag-2">process_flag/2</a></li>
<li title="process_flag-3"><a href="erlang.html#process_flag-3">process_flag/3</a></li>
<li title="process_info-1"><a href="erlang.html#process_info-1">process_info/1</a></li>
<li title="process_info-2"><a href="erlang.html#process_info-2">process_info/2</a></li>
<li title="processes-0"><a href="erlang.html#processes-0">processes/0</a></li>
<li title="purge_module-1"><a href="erlang.html#purge_module-1">purge_module/1</a></li>
<li title="put-2"><a href="erlang.html#put-2">put/2</a></li>
<li title="raise-3"><a href="erlang.html#raise-3">raise/3</a></li>
<li title="read_timer-1"><a href="erlang.html#read_timer-1">read_timer/1</a></li>
<li title="ref_to_list-1"><a href="erlang.html#ref_to_list-1">ref_to_list/1</a></li>
<li title="register-2"><a href="erlang.html#register-2">register/2</a></li>
<li title="registered-0"><a href="erlang.html#registered-0">registered/0</a></li>
<li title="resume_process-1"><a href="erlang.html#resume_process-1">resume_process/1</a></li>
<li title="round-1"><a href="erlang.html#round-1">round/1</a></li>
<li title="self-0"><a href="erlang.html#self-0">self/0</a></li>
<li title="send-2"><a href="erlang.html#send-2">send/2</a></li>
<li title="send-3"><a href="erlang.html#send-3">send/3</a></li>
<li title="send_after-3"><a href="erlang.html#send_after-3">send_after/3</a></li>
<li title="send_nosuspend-2"><a href="erlang.html#send_nosuspend-2">send_nosuspend/2</a></li>
<li title="send_nosuspend-3"><a href="erlang.html#send_nosuspend-3">send_nosuspend/3</a></li>
<li title="set_cookie-2"><a href="erlang.html#set_cookie-2">set_cookie/2</a></li>
<li title="setelement-3"><a href="erlang.html#setelement-3">setelement/3</a></li>
<li title="size-1"><a href="erlang.html#size-1">size/1</a></li>
<li title="spawn-1"><a href="erlang.html#spawn-1">spawn/1</a></li>
<li title="spawn-2"><a href="erlang.html#spawn-2">spawn/2</a></li>
<li title="spawn-3"><a href="erlang.html#spawn-3">spawn/3</a></li>
<li title="spawn-4"><a href="erlang.html#spawn-4">spawn/4</a></li>
<li title="spawn_link-1"><a href="erlang.html#spawn_link-1">spawn_link/1</a></li>
<li title="spawn_link-2"><a href="erlang.html#spawn_link-2">spawn_link/2</a></li>
<li title="spawn_link-3"><a href="erlang.html#spawn_link-3">spawn_link/3</a></li>
<li title="spawn_link-4"><a href="erlang.html#spawn_link-4">spawn_link/4</a></li>
<li title="spawn_monitor-1"><a href="erlang.html#spawn_monitor-1">spawn_monitor/1</a></li>
<li title="spawn_monitor-3"><a href="erlang.html#spawn_monitor-3">spawn_monitor/3</a></li>
<li title="spawn_opt-2"><a href="erlang.html#spawn_opt-2">spawn_opt/2</a></li>
<li title="spawn_opt-3"><a href="erlang.html#spawn_opt-3">spawn_opt/3</a></li>
<li title="spawn_opt-4"><a href="erlang.html#spawn_opt-4">spawn_opt/4</a></li>
<li title="spawn_opt-5"><a href="erlang.html#spawn_opt-5">spawn_opt/5</a></li>
<li title="split_binary-2"><a href="erlang.html#split_binary-2">split_binary/2</a></li>
<li title="start_timer-3"><a href="erlang.html#start_timer-3">start_timer/3</a></li>
<li title="statistics-1"><a href="erlang.html#statistics-1">statistics/1</a></li>
<li title="suspend_process-2"><a href="erlang.html#suspend_process-2">suspend_process/2</a></li>
<li title="suspend_process-1"><a href="erlang.html#suspend_process-1">suspend_process/1</a></li>
<li title="system_flag-2"><a href="erlang.html#system_flag-2">system_flag/2</a></li>
<li title="system_info-1"><a href="erlang.html#system_info-1">system_info/1</a></li>
<li title="system_monitor-0"><a href="erlang.html#system_monitor-0">system_monitor/0</a></li>
<li title="system_monitor-1"><a href="erlang.html#system_monitor-1">system_monitor/1</a></li>
<li title="system_monitor-2"><a href="erlang.html#system_monitor-2">system_monitor/2</a></li>
<li title="system_profile-0"><a href="erlang.html#system_profile-0">system_profile/0</a></li>
<li title="system_profile-2"><a href="erlang.html#system_profile-2">system_profile/2</a></li>
<li title="term_to_binary-1"><a href="erlang.html#term_to_binary-1">term_to_binary/1</a></li>
<li title="term_to_binary-2"><a href="erlang.html#term_to_binary-2">term_to_binary/2</a></li>
<li title="throw-1"><a href="erlang.html#throw-1">throw/1</a></li>
<li title="time-0"><a href="erlang.html#time-0">time/0</a></li>
<li title="tl-1"><a href="erlang.html#tl-1">tl/1</a></li>
<li title="trace-3"><a href="erlang.html#trace-3">trace/3</a></li>
<li title="trace_delivered-1"><a href="erlang.html#trace_delivered-1">trace_delivered/1</a></li>
<li title="trace_info-2"><a href="erlang.html#trace_info-2">trace_info/2</a></li>
<li title="trace_pattern-2"><a href="erlang.html#trace_pattern-2">trace_pattern/2</a></li>
<li title="trace_pattern-3"><a href="erlang.html#trace_pattern-3">trace_pattern/3</a></li>
<li title="trunc-1"><a href="erlang.html#trunc-1">trunc/1</a></li>
<li title="tuple_size-1"><a href="erlang.html#tuple_size-1">tuple_size/1</a></li>
<li title="tuple_to_list-1"><a href="erlang.html#tuple_to_list-1">tuple_to_list/1</a></li>
<li title="universaltime-0"><a href="erlang.html#universaltime-0">universaltime/0</a></li>
<li title="universaltime_to_localtime-1"><a href="erlang.html#universaltime_to_localtime-1">universaltime_to_localtime/1</a></li>
<li title="unlink-1"><a href="erlang.html#unlink-1">unlink/1</a></li>
<li title="unregister-1"><a href="erlang.html#unregister-1">unregister/1</a></li>
<li title="whereis-1"><a href="erlang.html#whereis-1">whereis/1</a></li>
<li title="yield-0"><a href="erlang.html#yield-0">yield/0</a></li>
</ul>
</li>
<li id="no" title="init " expanded="false">init<ul>
<li><a href="init.html">
Top of manual page
</a></li>
<li title="boot-1"><a href="init.html#boot-1">boot/1</a></li>
<li title="get_argument-1"><a href="init.html#get_argument-1">get_argument/1</a></li>
<li title="get_arguments-0"><a href="init.html#get_arguments-0">get_arguments/0</a></li>
<li title="get_plain_arguments-0"><a href="init.html#get_plain_arguments-0">get_plain_arguments/0</a></li>
<li title="get_status-0"><a href="init.html#get_status-0">get_status/0</a></li>
<li title="reboot-0"><a href="init.html#reboot-0">reboot/0</a></li>
<li title="restart-0"><a href="init.html#restart-0">restart/0</a></li>
<li title="script_id-0"><a href="init.html#script_id-0">script_id/0</a></li>
<li title="stop-0"><a href="init.html#stop-0">stop/0</a></li>
<li title="stop-1"><a href="init.html#stop-1">stop/1</a></li>
</ul>
</li>
<li id="no" title="zlib " expanded="false">zlib<ul>
<li><a href="zlib.html">
Top of manual page
</a></li>
<li title="open-0"><a href="zlib.html#open-0">open/0</a></li>
<li title="close-1"><a href="zlib.html#close-1">close/1</a></li>
<li title="deflateInit-1"><a href="zlib.html#deflateInit-1">deflateInit/1</a></li>
<li title="deflateInit-2"><a href="zlib.html#deflateInit-2">deflateInit/2</a></li>
<li title="deflateInit-6"><a href="zlib.html#deflateInit-6">deflateInit/6</a></li>
<li title="deflate-2"><a href="zlib.html#deflate-2">deflate/2</a></li>
<li title="deflate-3"><a href="zlib.html#deflate-3">deflate/3</a></li>
<li title="deflateSetDictionary-2"><a href="zlib.html#deflateSetDictionary-2">deflateSetDictionary/2</a></li>
<li title="deflateReset-1"><a href="zlib.html#deflateReset-1">deflateReset/1</a></li>
<li title="deflateParams-3"><a href="zlib.html#deflateParams-3">deflateParams/3</a></li>
<li title="deflateEnd-1"><a href="zlib.html#deflateEnd-1">deflateEnd/1</a></li>
<li title="inflateInit-1"><a href="zlib.html#inflateInit-1">inflateInit/1</a></li>
<li title="inflateInit-2"><a href="zlib.html#inflateInit-2">inflateInit/2</a></li>
<li title="inflate-2"><a href="zlib.html#inflate-2">inflate/2</a></li>
<li title="inflateSetDictionary-2"><a href="zlib.html#inflateSetDictionary-2">inflateSetDictionary/2</a></li>
<li title="inflateReset-1"><a href="zlib.html#inflateReset-1">inflateReset/1</a></li>
<li title="inflateEnd-1"><a href="zlib.html#inflateEnd-1">inflateEnd/1</a></li>
<li title="setBufSize-2"><a href="zlib.html#setBufSize-2">setBufSize/2</a></li>
<li title="getBufSize-1"><a href="zlib.html#getBufSize-1">getBufSize/1</a></li>
<li title="crc32-1"><a href="zlib.html#crc32-1">crc32/1</a></li>
<li title="crc32-2"><a href="zlib.html#crc32-2">crc32/2</a></li>
<li title="crc32-3"><a href="zlib.html#crc32-3">crc32/3</a></li>
<li title="crc32_combine-4"><a href="zlib.html#crc32_combine-4">crc32_combine/4</a></li>
<li title="adler32-2"><a href="zlib.html#adler32-2">adler32/2</a></li>
<li title="adler32-3"><a href="zlib.html#adler32-3">adler32/3</a></li>
<li title="adler32_combine-4"><a href="zlib.html#adler32_combine-4">adler32_combine/4</a></li>
<li title="compress-1"><a href="zlib.html#compress-1">compress/1</a></li>
<li title="uncompress-1"><a href="zlib.html#uncompress-1">uncompress/1</a></li>
<li title="zip-1"><a href="zlib.html#zip-1">zip/1</a></li>
<li title="unzip-1"><a href="zlib.html#unzip-1">unzip/1</a></li>
<li title="gzip-1"><a href="zlib.html#gzip-1">gzip/1</a></li>
<li title="gunzip-1"><a href="zlib.html#gunzip-1">gunzip/1</a></li>
</ul>
</li>
<li title="epmd"><a href="epmd.html">epmd</a></li>
<li title="erl"><a href="erl.html">erl</a></li>
<li title="erlc"><a href="erlc.html">erlc</a></li>
<li title="werl"><a href="werl.html">werl</a></li>
<li title="escript"><a href="escript.html">escript</a></li>
<li title="erlsrv"><a href="erlsrv.html">erlsrv</a></li>
<li title="start_erl"><a href="start_erl.html">start_erl</a></li>
<li id="no" title="erl_set_memory_block " expanded="false">erl_set_memory_block<ul>
<li><a href="erl_set_memory_block.html">
Top of manual page
</a></li>
<li title="erl_set_memory_block"><a href="erl_set_memory_block.html#erl_set_memory_block">erl_set_memory_block()
</a></li>
<li title="erl_memory_show"><a href="erl_set_memory_block.html#erl_memory_show">erl_memory_show()
</a></li>
<li title="erl_mem_info_get"><a href="erl_set_memory_block.html#erl_mem_info_get">erl_mem_info_get()
</a></li>
</ul>
</li>
<li title="run_erl"><a href="run_erl.html">run_erl</a></li>
<li title="start"><a href="start.html">start</a></li>
<li id="loadscrollpos" title="erl_driver " expanded="true">erl_driver<ul>
<li><a href="erl_driver.html">
Top of manual page
</a></li>
<li title="driver_system_info"><a href="erl_driver.html#driver_system_info">driver_system_info()
</a></li>
<li title="driver_output"><a href="erl_driver.html#driver_output">driver_output()
</a></li>
<li title="driver_output2"><a href="erl_driver.html#driver_output2">driver_output2()
</a></li>
<li title="driver_output_binary"><a href="erl_driver.html#driver_output_binary">driver_output_binary()
</a></li>
<li title="driver_outputv"><a href="erl_driver.html#driver_outputv">driver_outputv()
</a></li>
<li title="driver_vec_to_buf"><a href="erl_driver.html#driver_vec_to_buf">driver_vec_to_buf()
</a></li>
<li title="driver_set_timer"><a href="erl_driver.html#driver_set_timer">driver_set_timer()
</a></li>
<li title="driver_cancel_timer"><a href="erl_driver.html#driver_cancel_timer">driver_cancel_timer()
</a></li>
<li title="driver_read_timer"><a href="erl_driver.html#driver_read_timer">driver_read_timer()
</a></li>
<li title="driver_get_now"><a href="erl_driver.html#driver_get_now">driver_get_now()
</a></li>
<li title="driver_select"><a href="erl_driver.html#driver_select">driver_select()
</a></li>
<li title="driver_alloc"><a href="erl_driver.html#driver_alloc">driver_alloc()
</a></li>
<li title="driver_realloc"><a href="erl_driver.html#driver_realloc">driver_realloc()
</a></li>
<li title="driver_free"><a href="erl_driver.html#driver_free">driver_free()
</a></li>
<li title="driver_alloc_binary"><a href="erl_driver.html#driver_alloc_binary">driver_alloc_binary()
</a></li>
<li title="driver_realloc_binary"><a href="erl_driver.html#driver_realloc_binary">driver_realloc_binary()
</a></li>
<li title="driver_free_binary"><a href="erl_driver.html#driver_free_binary">driver_free_binary()
</a></li>
<li title="driver_binary_get_refc"><a href="erl_driver.html#driver_binary_get_refc">driver_binary_get_refc()
</a></li>
<li title="driver_binary_inc_refc"><a href="erl_driver.html#driver_binary_inc_refc">driver_binary_inc_refc()
</a></li>
<li title="driver_binary_dec_refc"><a href="erl_driver.html#driver_binary_dec_refc">driver_binary_dec_refc()
</a></li>
<li title="driver_enq"><a href="erl_driver.html#driver_enq">driver_enq()
</a></li>
<li title="driver_pushq"><a href="erl_driver.html#driver_pushq">driver_pushq()
</a></li>
<li title="driver_deq"><a href="erl_driver.html#driver_deq">driver_deq()
</a></li>
<li title="driver_sizeq"><a href="erl_driver.html#driver_sizeq">driver_sizeq()
</a></li>
<li title="driver_enq_bin"><a href="erl_driver.html#driver_enq_bin">driver_enq_bin()
</a></li>
<li title="driver_pushq_bin"><a href="erl_driver.html#driver_pushq_bin">driver_pushq_bin()
</a></li>
<li title="driver_peekqv"><a href="erl_driver.html#driver_peekqv">driver_peekqv()
</a></li>
<li title="driver_peekq"><a href="erl_driver.html#driver_peekq">driver_peekq()
</a></li>
<li title="driver_enqv"><a href="erl_driver.html#driver_enqv">driver_enqv()
</a></li>
<li title="driver_pushqv"><a href="erl_driver.html#driver_pushqv">driver_pushqv()
</a></li>
<li title="driver_pdl_create"><a href="erl_driver.html#driver_pdl_create">driver_pdl_create()
</a></li>
<li title="driver_pdl_lock"><a href="erl_driver.html#driver_pdl_lock">driver_pdl_lock()
</a></li>
<li title="driver_pdl_unlock"><a href="erl_driver.html#driver_pdl_unlock">driver_pdl_unlock()
</a></li>
<li title="driver_pdl_get_refc"><a href="erl_driver.html#driver_pdl_get_refc">driver_pdl_get_refc()
</a></li>
<li title="driver_pdl_inc_refc"><a href="erl_driver.html#driver_pdl_inc_refc">driver_pdl_inc_refc()
</a></li>
<li title="driver_pdl_dec_refc"><a href="erl_driver.html#driver_pdl_dec_refc">driver_pdl_dec_refc()
</a></li>
<li title="driver_monitor_process"><a href="erl_driver.html#driver_monitor_process">driver_monitor_process()
</a></li>
<li title="driver_demonitor_process"><a href="erl_driver.html#driver_demonitor_process">driver_demonitor_process()
</a></li>
<li title="driver_get_monitored_process"><a href="erl_driver.html#driver_get_monitored_process">driver_get_monitored_process()
</a></li>
<li title="driver_compare_monitors"><a href="erl_driver.html#driver_compare_monitors">driver_compare_monitors()
</a></li>
<li title="add_driver_entry"><a href="erl_driver.html#add_driver_entry">add_driver_entry()
</a></li>
<li title="remove_driver_entry"><a href="erl_driver.html#remove_driver_entry">remove_driver_entry()
</a></li>
<li title="erl_errno_id"><a href="erl_driver.html#erl_errno_id">erl_errno_id()
</a></li>
<li title="set_busy_port"><a href="erl_driver.html#set_busy_port">set_busy_port()
</a></li>
<li title="set_port_control_flags"><a href="erl_driver.html#set_port_control_flags">set_port_control_flags()
</a></li>
<li title="driver_failure_eof"><a href="erl_driver.html#driver_failure_eof">driver_failure_eof()
</a></li>
<li title="driver_failure_atom"><a href="erl_driver.html#driver_failure_atom">driver_failure_atom()
</a></li>
<li title="driver_failure_posix"><a href="erl_driver.html#driver_failure_posix">driver_failure_posix()
</a></li>
<li title="driver_failure"><a href="erl_driver.html#driver_failure">driver_failure()
</a></li>
<li title="driver_connected"><a href="erl_driver.html#driver_connected">driver_connected()
</a></li>
<li title="driver_caller"><a href="erl_driver.html#driver_caller">driver_caller()
</a></li>
<li title="driver_output_term"><a href="erl_driver.html#driver_output_term">driver_output_term()
</a></li>
<li title="driver_mk_atom"><a href="erl_driver.html#driver_mk_atom">driver_mk_atom()
</a></li>
<li title="driver_mk_port"><a href="erl_driver.html#driver_mk_port">driver_mk_port()
</a></li>
<li title="driver_send_term"><a href="erl_driver.html#driver_send_term">driver_send_term()
</a></li>
<li title="driver_async "><a href="erl_driver.html#driver_async%20">driver_async ()
</a></li>
<li title="driver_async_cancel"><a href="erl_driver.html#driver_async_cancel">driver_async_cancel()
</a></li>
<li title="driver_lock_driver"><a href="erl_driver.html#driver_lock_driver">driver_lock_driver()
</a></li>
<li title="driver_create_port"><a href="erl_driver.html#driver_create_port">driver_create_port()
</a></li>
<li title="erl_drv_thread_create"><a href="erl_driver.html#erl_drv_thread_create">erl_drv_thread_create()
</a></li>
<li title="erl_drv_thread_opts_create"><a href="erl_driver.html#erl_drv_thread_opts_create">erl_drv_thread_opts_create()
</a></li>
<li title="erl_drv_thread_opts_destroy"><a href="erl_driver.html#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy()
</a></li>
<li title="erl_drv_thread_exit"><a href="erl_driver.html#erl_drv_thread_exit">erl_drv_thread_exit()
</a></li>
<li title="erl_drv_thread_join"><a href="erl_driver.html#erl_drv_thread_join">erl_drv_thread_join()
</a></li>
<li title="erl_drv_thread_self"><a href="erl_driver.html#erl_drv_thread_self">erl_drv_thread_self()
</a></li>
<li title="erl_drv_equal_tids"><a href="erl_driver.html#erl_drv_equal_tids">erl_drv_equal_tids()
</a></li>
<li title="erl_drv_mutex_create"><a href="erl_driver.html#erl_drv_mutex_create">erl_drv_mutex_create()
</a></li>
<li title="erl_drv_mutex_destroy"><a href="erl_driver.html#erl_drv_mutex_destroy">erl_drv_mutex_destroy()
</a></li>
<li title="erl_drv_mutex_lock"><a href="erl_driver.html#erl_drv_mutex_lock">erl_drv_mutex_lock()
</a></li>
<li title="erl_drv_mutex_trylock"><a href="erl_driver.html#erl_drv_mutex_trylock">erl_drv_mutex_trylock()
</a></li>
<li title="erl_drv_mutex_unlock"><a href="erl_driver.html#erl_drv_mutex_unlock">erl_drv_mutex_unlock()
</a></li>
<li title="erl_drv_cond_create"><a href="erl_driver.html#erl_drv_cond_create">erl_drv_cond_create()
</a></li>
<li title="erl_drv_cond_destroy"><a href="erl_driver.html#erl_drv_cond_destroy">erl_drv_cond_destroy()
</a></li>
<li title="erl_drv_cond_signal"><a href="erl_driver.html#erl_drv_cond_signal">erl_drv_cond_signal()
</a></li>
<li title="erl_drv_cond_broadcast"><a href="erl_driver.html#erl_drv_cond_broadcast">erl_drv_cond_broadcast()
</a></li>
<li title="erl_drv_cond_wait"><a href="erl_driver.html#erl_drv_cond_wait">erl_drv_cond_wait()
</a></li>
<li title="erl_drv_rwlock_create"><a href="erl_driver.html#erl_drv_rwlock_create">erl_drv_rwlock_create()
</a></li>
<li title="erl_drv_rwlock_destroy"><a href="erl_driver.html#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy()
</a></li>
<li title="erl_drv_rwlock_rlock"><a href="erl_driver.html#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock()
</a></li>
<li title="erl_drv_rwlock_tryrlock"><a href="erl_driver.html#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock()
</a></li>
<li title="erl_drv_rwlock_runlock"><a href="erl_driver.html#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock()
</a></li>
<li title="erl_drv_rwlock_rwlock"><a href="erl_driver.html#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock()
</a></li>
<li title="erl_drv_rwlock_tryrwlock"><a href="erl_driver.html#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock()
</a></li>
<li title="erl_drv_rwlock_rwunlock"><a href="erl_driver.html#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock()
</a></li>
<li title="erl_drv_tsd_key_create"><a href="erl_driver.html#erl_drv_tsd_key_create">erl_drv_tsd_key_create()
</a></li>
<li title="erl_drv_tsd_key_destroy"><a href="erl_driver.html#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy()
</a></li>
<li title="erl_drv_tsd_set"><a href="erl_driver.html#erl_drv_tsd_set">erl_drv_tsd_set()
</a></li>
<li title="erl_drv_tsd_get"><a href="erl_driver.html#erl_drv_tsd_get">erl_drv_tsd_get()
</a></li>
<li title="erl_drv_putenv"><a href="erl_driver.html#erl_drv_putenv">erl_drv_putenv()
</a></li>
<li title="erl_drv_getenv"><a href="erl_driver.html#erl_drv_getenv">erl_drv_getenv()
</a></li>
</ul>
</li>
<li title="driver_entry"><a href="driver_entry.html">driver_entry</a></li>
<li title="erts_alloc"><a href="erts_alloc.html">erts_alloc</a></li>
<li id="no" title="erl_nif " expanded="false">erl_nif<ul>
<li><a href="erl_nif.html">
Top of manual page
</a></li>
<li title="enif_alloc"><a href="erl_nif.html#enif_alloc">enif_alloc()
</a></li>
<li title="enif_alloc_binary"><a href="erl_nif.html#enif_alloc_binary">enif_alloc_binary()
</a></li>
<li title="enif_alloc_env"><a href="erl_nif.html#enif_alloc_env">enif_alloc_env()
</a></li>
<li title="enif_alloc_resource"><a href="erl_nif.html#enif_alloc_resource">enif_alloc_resource()
</a></li>
<li title="enif_clear_env"><a href="erl_nif.html#enif_clear_env">enif_clear_env()
</a></li>
<li title="enif_compare"><a href="erl_nif.html#enif_compare">enif_compare()
</a></li>
<li title="enif_cond_broadcast"><a href="erl_nif.html#enif_cond_broadcast">enif_cond_broadcast()
</a></li>
<li title="enif_cond_create"><a href="erl_nif.html#enif_cond_create">enif_cond_create()
</a></li>
<li title="enif_cond_destroy"><a href="erl_nif.html#enif_cond_destroy">enif_cond_destroy()
</a></li>
<li title="enif_cond_signal"><a href="erl_nif.html#enif_cond_signal">enif_cond_signal()
</a></li>
<li title="enif_cond_wait"><a href="erl_nif.html#enif_cond_wait">enif_cond_wait()
</a></li>
<li title="enif_equal_tids"><a href="erl_nif.html#enif_equal_tids">enif_equal_tids()
</a></li>
<li title="enif_free"><a href="erl_nif.html#enif_free">enif_free()
</a></li>
<li title="enif_free_env"><a href="erl_nif.html#enif_free_env">enif_free_env()
</a></li>
<li title="enif_get_atom"><a href="erl_nif.html#enif_get_atom">enif_get_atom()
</a></li>
<li title="enif_get_atom_length"><a href="erl_nif.html#enif_get_atom_length">enif_get_atom_length()
</a></li>
<li title="enif_get_double"><a href="erl_nif.html#enif_get_double">enif_get_double()
</a></li>
<li title="enif_get_int"><a href="erl_nif.html#enif_get_int">enif_get_int()
</a></li>
<li title="enif_get_int64"><a href="erl_nif.html#enif_get_int64">enif_get_int64()
</a></li>
<li title="enif_get_local_pid"><a href="erl_nif.html#enif_get_local_pid">enif_get_local_pid()
</a></li>
<li title="enif_get_list_cell"><a href="erl_nif.html#enif_get_list_cell">enif_get_list_cell()
</a></li>
<li title="enif_get_list_length"><a href="erl_nif.html#enif_get_list_length">enif_get_list_length()
</a></li>
<li title="enif_get_long"><a href="erl_nif.html#enif_get_long">enif_get_long()
</a></li>
<li title="enif_get_resource"><a href="erl_nif.html#enif_get_resource">enif_get_resource()
</a></li>
<li title="enif_get_string"><a href="erl_nif.html#enif_get_string">enif_get_string()
</a></li>
<li title="enif_get_tuple"><a href="erl_nif.html#enif_get_tuple">enif_get_tuple()
</a></li>
<li title="enif_get_uint"><a href="erl_nif.html#enif_get_uint">enif_get_uint()
</a></li>
<li title="enif_get_uint64"><a href="erl_nif.html#enif_get_uint64">enif_get_uint64()
</a></li>
<li title="enif_get_ulong"><a href="erl_nif.html#enif_get_ulong">enif_get_ulong()
</a></li>
<li title="enif_inspect_binary"><a href="erl_nif.html#enif_inspect_binary">enif_inspect_binary()
</a></li>
<li title="enif_inspect_iolist_as_binary"><a href="erl_nif.html#enif_inspect_iolist_as_binary">enif_inspect_iolist_as_binary()
</a></li>
<li title="enif_is_atom"><a href="erl_nif.html#enif_is_atom">enif_is_atom()
</a></li>
<li title="enif_is_binary"><a href="erl_nif.html#enif_is_binary">enif_is_binary()
</a></li>
<li title="enif_is_empty_list"><a href="erl_nif.html#enif_is_empty_list">enif_is_empty_list()
</a></li>
<li title="enif_is_exception"><a href="erl_nif.html#enif_is_exception">enif_is_exception()
</a></li>
<li title="enif_is_number"><a href="erl_nif.html#enif_is_number">enif_is_number()
</a></li>
<li title="enif_is_fun"><a href="erl_nif.html#enif_is_fun">enif_is_fun()
</a></li>
<li title="enif_is_identical"><a href="erl_nif.html#enif_is_identical">enif_is_identical()
</a></li>
<li title="enif_is_pid"><a href="erl_nif.html#enif_is_pid">enif_is_pid()
</a></li>
<li title="enif_is_port"><a href="erl_nif.html#enif_is_port">enif_is_port()
</a></li>
<li title="enif_is_ref"><a href="erl_nif.html#enif_is_ref">enif_is_ref()
</a></li>
<li title="enif_is_tuple"><a href="erl_nif.html#enif_is_tuple">enif_is_tuple()
</a></li>
<li title="enif_is_list"><a href="erl_nif.html#enif_is_list">enif_is_list()
</a></li>
<li title="enif_keep_resource"><a href="erl_nif.html#enif_keep_resource">enif_keep_resource()
</a></li>
<li title="enif_make_atom"><a href="erl_nif.html#enif_make_atom">enif_make_atom()
</a></li>
<li title="enif_make_atom_len"><a href="erl_nif.html#enif_make_atom_len">enif_make_atom_len()
</a></li>
<li title="enif_make_badarg"><a href="erl_nif.html#enif_make_badarg">enif_make_badarg()
</a></li>
<li title="enif_make_binary"><a href="erl_nif.html#enif_make_binary">enif_make_binary()
</a></li>
<li title="enif_make_copy"><a href="erl_nif.html#enif_make_copy">enif_make_copy()
</a></li>
<li title="enif_make_double"><a href="erl_nif.html#enif_make_double">enif_make_double()
</a></li>
<li title="enif_make_existing_atom"><a href="erl_nif.html#enif_make_existing_atom">enif_make_existing_atom()
</a></li>
<li title="enif_make_existing_atom_len"><a href="erl_nif.html#enif_make_existing_atom_len">enif_make_existing_atom_len()
</a></li>
<li title="enif_make_int"><a href="erl_nif.html#enif_make_int">enif_make_int()
</a></li>
<li title="enif_make_int64"><a href="erl_nif.html#enif_make_int64">enif_make_int64()
</a></li>
<li title="enif_make_list"><a href="erl_nif.html#enif_make_list">enif_make_list()
</a></li>
<li title="enif_make_list1"><a href="erl_nif.html#enif_make_list1">enif_make_list1()
</a></li>
<li title="enif_make_list2"><a href="erl_nif.html#enif_make_list2">enif_make_list2()
</a></li>
<li title="enif_make_list3"><a href="erl_nif.html#enif_make_list3">enif_make_list3()
</a></li>
<li title="enif_make_list4"><a href="erl_nif.html#enif_make_list4">enif_make_list4()
</a></li>
<li title="enif_make_list5"><a href="erl_nif.html#enif_make_list5">enif_make_list5()
</a></li>
<li title="enif_make_list6"><a href="erl_nif.html#enif_make_list6">enif_make_list6()
</a></li>
<li title="enif_make_list7"><a href="erl_nif.html#enif_make_list7">enif_make_list7()
</a></li>
<li title="enif_make_list8"><a href="erl_nif.html#enif_make_list8">enif_make_list8()
</a></li>
<li title="enif_make_list9"><a href="erl_nif.html#enif_make_list9">enif_make_list9()
</a></li>
<li title="enif_make_list_cell"><a href="erl_nif.html#enif_make_list_cell">enif_make_list_cell()
</a></li>
<li title="enif_make_list_from_array"><a href="erl_nif.html#enif_make_list_from_array">enif_make_list_from_array()
</a></li>
<li title="enif_make_reverse_list"><a href="erl_nif.html#enif_make_reverse_list">enif_make_reverse_list()
</a></li>
<li title="enif_make_long"><a href="erl_nif.html#enif_make_long">enif_make_long()
</a></li>
<li title="enif_make_new_binary"><a href="erl_nif.html#enif_make_new_binary">enif_make_new_binary()
</a></li>
<li title="enif_make_pid"><a href="erl_nif.html#enif_make_pid">enif_make_pid()
</a></li>
<li title="enif_make_ref"><a href="erl_nif.html#enif_make_ref">enif_make_ref()
</a></li>
<li title="enif_make_resource"><a href="erl_nif.html#enif_make_resource">enif_make_resource()
</a></li>
<li title="enif_make_resource_binary"><a href="erl_nif.html#enif_make_resource_binary">enif_make_resource_binary()
</a></li>
<li title="enif_make_string"><a href="erl_nif.html#enif_make_string">enif_make_string()
</a></li>
<li title="enif_make_string_len"><a href="erl_nif.html#enif_make_string_len">enif_make_string_len()
</a></li>
<li title="enif_make_sub_binary"><a href="erl_nif.html#enif_make_sub_binary">enif_make_sub_binary()
</a></li>
<li title="enif_make_tuple"><a href="erl_nif.html#enif_make_tuple">enif_make_tuple()
</a></li>
<li title="enif_make_tuple1"><a href="erl_nif.html#enif_make_tuple1">enif_make_tuple1()
</a></li>
<li title="enif_make_tuple2"><a href="erl_nif.html#enif_make_tuple2">enif_make_tuple2()
</a></li>
<li title="enif_make_tuple3"><a href="erl_nif.html#enif_make_tuple3">enif_make_tuple3()
</a></li>
<li title="enif_make_tuple4"><a href="erl_nif.html#enif_make_tuple4">enif_make_tuple4()
</a></li>
<li title="enif_make_tuple5"><a href="erl_nif.html#enif_make_tuple5">enif_make_tuple5()
</a></li>
<li title="enif_make_tuple6"><a href="erl_nif.html#enif_make_tuple6">enif_make_tuple6()
</a></li>
<li title="enif_make_tuple7"><a href="erl_nif.html#enif_make_tuple7">enif_make_tuple7()
</a></li>
<li title="enif_make_tuple8"><a href="erl_nif.html#enif_make_tuple8">enif_make_tuple8()
</a></li>
<li title="enif_make_tuple9"><a href="erl_nif.html#enif_make_tuple9">enif_make_tuple9()
</a></li>
<li title="enif_make_tuple_from_array"><a href="erl_nif.html#enif_make_tuple_from_array">enif_make_tuple_from_array()
</a></li>
<li title="enif_make_uint"><a href="erl_nif.html#enif_make_uint">enif_make_uint()
</a></li>
<li title="enif_make_uint64"><a href="erl_nif.html#enif_make_uint64">enif_make_uint64()
</a></li>
<li title="enif_make_ulong"><a href="erl_nif.html#enif_make_ulong">enif_make_ulong()
</a></li>
<li title="enif_mutex_create"><a href="erl_nif.html#enif_mutex_create">enif_mutex_create()
</a></li>
<li title="enif_mutex_destroy"><a href="erl_nif.html#enif_mutex_destroy">enif_mutex_destroy()
</a></li>
<li title="enif_mutex_lock"><a href="erl_nif.html#enif_mutex_lock">enif_mutex_lock()
</a></li>
<li title="enif_mutex_trylock"><a href="erl_nif.html#enif_mutex_trylock">enif_mutex_trylock()
</a></li>
<li title="enif_mutex_unlock"><a href="erl_nif.html#enif_mutex_unlock">enif_mutex_unlock()
</a></li>
<li title="enif_open_resource_type"><a href="erl_nif.html#enif_open_resource_type">enif_open_resource_type()
</a></li>
<li title="enif_priv_data"><a href="erl_nif.html#enif_priv_data">enif_priv_data()
</a></li>
<li title="enif_realloc_binary"><a href="erl_nif.html#enif_realloc_binary">enif_realloc_binary()
</a></li>
<li title="enif_release_binary"><a href="erl_nif.html#enif_release_binary">enif_release_binary()
</a></li>
<li title="enif_release_resource"><a href="erl_nif.html#enif_release_resource">enif_release_resource()
</a></li>
<li title="enif_rwlock_create"><a href="erl_nif.html#enif_rwlock_create">enif_rwlock_create()
</a></li>
<li title="enif_rwlock_destroy"><a href="erl_nif.html#enif_rwlock_destroy">enif_rwlock_destroy()
</a></li>
<li title="enif_rwlock_rlock"><a href="erl_nif.html#enif_rwlock_rlock">enif_rwlock_rlock()
</a></li>
<li title="enif_rwlock_runlock"><a href="erl_nif.html#enif_rwlock_runlock">enif_rwlock_runlock()
</a></li>
<li title="enif_rwlock_rwlock"><a href="erl_nif.html#enif_rwlock_rwlock">enif_rwlock_rwlock()
</a></li>
<li title="enif_rwlock_rwunlock"><a href="erl_nif.html#enif_rwlock_rwunlock">enif_rwlock_rwunlock()
</a></li>
<li title="enif_rwlock_tryrlock"><a href="erl_nif.html#enif_rwlock_tryrlock">enif_rwlock_tryrlock()
</a></li>
<li title="enif_rwlock_tryrwlock"><a href="erl_nif.html#enif_rwlock_tryrwlock">enif_rwlock_tryrwlock()
</a></li>
<li title="enif_self"><a href="erl_nif.html#enif_self">enif_self()
</a></li>
<li title="enif_send"><a href="erl_nif.html#enif_send">enif_send()
</a></li>
<li title="enif_sizeof_resource"><a href="erl_nif.html#enif_sizeof_resource">enif_sizeof_resource()
</a></li>
<li title="enif_system_info"><a href="erl_nif.html#enif_system_info">enif_system_info()
</a></li>
<li title="enif_thread_create"><a href="erl_nif.html#enif_thread_create">enif_thread_create()
</a></li>
<li title="enif_thread_exit"><a href="erl_nif.html#enif_thread_exit">enif_thread_exit()
</a></li>
<li title="enif_thread_join"><a href="erl_nif.html#enif_thread_join">enif_thread_join()
</a></li>
<li title="enif_thread_opts_create"><a href="erl_nif.html#enif_thread_opts_create">enif_thread_opts_create()
</a></li>
<li title="enif_thread_opts_destroy"><a href="erl_nif.html#enif_thread_opts_destroy">enif_thread_opts_destroy()
</a></li>
<li title="enif_thread_self"><a href="erl_nif.html#enif_thread_self">enif_thread_self()
</a></li>
<li title="enif_tsd_key_create"><a href="erl_nif.html#enif_tsd_key_create">enif_tsd_key_create()
</a></li>
<li title="enif_tsd_key_destroy"><a href="erl_nif.html#enif_tsd_key_destroy">enif_tsd_key_destroy()
</a></li>
<li title="enif_tsd_get"><a href="erl_nif.html#enif_tsd_get">enif_tsd_get()
</a></li>
<li title="enif_tsd_set"><a href="erl_nif.html#enif_tsd_set">enif_tsd_set()
</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>erl_driver</h1></center>
<h3>C LIBRARY</h3>
<div class="REFBODY">erl_driver</div>
<h3>LIBRARY SUMMARY</h3>
<div class="REFBODY">API functions for an Erlang driver</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>An Erlang driver is a library containing a set of native driver
callback functions that the Erlang VM calls when certain
events occur. There may be multiple instances of a driver, each
instance is associated with an Erlang port.</p>
<a name="WARNING"></a>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p><strong>Use this functionality with extreme care!</strong></p>
<p>A driver callback is executed as a direct extension of the
native code of the VM. Execution is not made in a safe environment.
The VM can <strong>not</strong> provide the same services as provided when
executing Erlang code, such as preemptive scheduling or memory
protection. If the driver callback function doesn't behave well,
the whole VM will misbehave.</p>
<ul>
<li><p>A driver callback that crash will crash the whole VM.</p></li>
<li><p>An erroneously implemented driver callback might cause
a VM internal state inconsistency which may cause a crash of the VM,
or miscellaneous misbehaviors of the VM at any point after the call
to the driver callback.</p></li>
<li><p>A driver callback that do <span class="bold_code"><a href="#lengthy_work">lengthy
work</a></span> before returning will degrade responsiveness of the VM,
and may cause miscellaneous strange behaviors. Such strange behaviors
include, but are not limited to, extreme memory usage, and bad load
balancing between schedulers. Strange behaviors that might occur due
to lengthy work may also vary between OTP releases.</p></li>
</ul>
</p></div>
</div>
<p>As of erts version 5.5.3 the driver interface has been extended
(see <span class="bold_code"><a href="driver_entry.html#extended_marker">extended marker</a></span>).
The extended interface introduce
<span class="bold_code"><a href="#version_management">version management</a></span>,
the possibility to pass capability flags
(see <span class="bold_code"><a href="driver_entry.html#driver_flags">driver flags</a></span>)
to the runtime system at driver initialization, and some new
driver API functions. </p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>As of erts version 5.9 old drivers have to be recompiled
and have to use the extended interface. They also have to be
adjusted to the
<span class="bold_code"><a href="#rewrites_for_64_bits">64-bit capable driver interface.
</a></span>
</p>
</p></div>
</div>
<p>The driver calls back to the emulator, using the API
functions declared in <span class="code">erl_driver.h</span>. They are used for
outputting data from the driver, using timers, etc.</p>
<p>Each driver instance is associated with a port. Every port
has a port owner process. Communication with the port is normally
done through the port owner process. Most of the functions take
the <span class="code">port</span> handle as an argument. This identifies the driver
instance. Note that this port handle must be stored by the driver,
it is not given when the driver is called from the emulator (see
<span class="bold_code"><a href="driver_entry.html#emulator">driver_entry</a></span>).</p>
<p>Some of the functions take a parameter of type
<span class="code">ErlDrvBinary</span>, a driver binary. It should be both
allocated and freed by the caller. Using a binary directly avoids
one extra copying of data.</p>
<p>Many of the output functions have a "header buffer", with
<span class="code">hbuf</span> and <span class="code">hlen</span> parameters. This buffer is sent as a
list before the binary (or list, depending on port mode) that is
sent. This is convenient when matching on messages received from
the port. (Although in the latest versions of Erlang, there is
the binary syntax, that enables you to match on the beginning of
a binary.)
<a name="smp_support"></a>
</p>
<p>In the runtime system with SMP support, drivers are locked either
on driver level or port level (driver instance level). By default
driver level locking will be used, i.e., only one emulator thread
will execute code in the driver at a time. If port level locking
is used, multiple emulator threads may execute code in the driver
at the same time. There will only be one thread at a time calling
driver call-backs corresponding to the same port, though. In order
to enable port level locking set the <span class="code">ERL_DRV_FLAG_USE_PORT_LOCKING</span>
<span class="bold_code"><a href="driver_entry.html#driver_flags">driver flag</a></span> in
the <span class="bold_code"><a href="driver_entry.html">driver_entry</a></span>
used by the driver. When port level locking is used it is the
responsibility of the driver writer to synchronize all accesses
to data shared by the ports (driver instances).</p>
<p>Most drivers written before the runtime system with SMP
support existed will be able to run in the runtime system
with SMP support without being rewritten if driver
level locking is used.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>It is assumed that drivers do not access other drivers. If
drivers should access each other they have to provide their own
mechanism for thread safe synchronization. Such "inter driver
communication" is strongly discouraged.</p>
</p></div>
</div>
<p>Previously, in the runtime system without SMP support,
specific driver call-backs were always called from the same
thread. This is <strong>not</strong> the case in the runtime system
with SMP support. Regardless of locking scheme used, calls
to driver call-backs may be made from different threads, e.g.,
two consecutive calls to exactly the same call-back for exactly
the same port may be made from two different threads. This
will for <strong>most</strong> drivers not be a problem, but it might.
Drivers that depend on all call-backs being called in the
same thread, <strong>have</strong> to be rewritten before being used
in the runtime system with SMP support.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Regardless of locking scheme used, calls to driver
call-backs may be made from different threads.</p>
</p></div>
</div>
<p>Most functions in this API are <strong>not</strong> thread-safe, i.e.,
they may <strong>not</strong> be called from an arbitrary thread. Functions
that are not documented as thread-safe may only be called from
driver call-backs or function calls descending from a driver
call-back call. Note that driver call-backs may be called from
different threads. This, however, is not a problem for any
function in this API, since the emulator has control over
these threads.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Functions not explicitly documented as thread-safe are
<strong>not</strong> thread-safe. Also note that some functions
are <strong>only</strong> thread safe when used in a runtime
system with SMP support.</p>
</p></div>
</div>
<p><a name="lengthy_work"></a>
As mentioned in the <span class="bold_code"><a href="#WARNING">warning</a></span> text at
the beginning of this document it is of vital importance that a driver callback
does return relatively fast. It is hard to give an exact maximum amount
of time that a driver callback is allowed to work, but as a rule of thumb
a well behaving driver callback should return before a millisecond has
passed. This can be achieved using different approaches.
If you have full control over the code that are to execute in the driver
callback, the best approach is to divide the work into multiple chunks of
work and trigger multiple calls to the
<span class="bold_code"><a href="driver_entry.html#timeout">timeout callback</a></span> using
zero timeouts. This might, however, not always be possible, e.g. when
calling third party libraries. In this case you typically want to dispatch
the work to another thread. Information about thread primitives can be
found below.</p>
</p></div>
<h3><a name="id160980">FUNCTIONALITY</a></h3>
<div class="REFBODY">
<p>All functions that a driver needs to do with Erlang are
performed through driver API functions. There are functions
for the following functionality:</p>
<dl>
<dt><strong>Timer functions</strong></dt>
<dd>Timer functions are used to control the timer that a driver
may use. The timer will have the emulator call the
<span class="bold_code"><a href="driver_entry.html#timeout">timeout</a></span> entry
function after a specified time. Only one timer is available
for each driver instance.</dd>
<dt><strong>Queue handling</strong></dt>
<dd>
<p>Every driver instance has an associated queue. This queue is a
<span class="code">SysIOVec</span> that works as a buffer. It's mostly used for
the driver to buffer data that should be written to a device,
it is a byte stream. If the port owner process closes the
driver, and the queue is not empty, the driver will not be
closed. This enables the driver to flush its buffers before
closing.</p>
<p>The queue can be manipulated from arbitrary threads if
a port data lock is used. See documentation of the
<span class="bold_code"><a href="#ErlDrvPDL">ErlDrvPDL</a></span> type for
more information.</p>
</dd>
<dt><strong>Output functions</strong></dt>
<dd>With the output functions, the driver sends data back to
the emulator. They will be received as messages by the port owner
process, see <span class="code">open_port/2</span>. The vector function and the
function taking a driver binary are faster, because they avoid
copying the data buffer. There is also a fast way of sending
terms from the driver, without going through the binary term
format.</dd>
<dt><strong>Failure</strong></dt>
<dd>The driver can exit and signal errors up to Erlang. This is
only for severe errors, when the driver can't possibly keep
open.</dd>
<dt><strong>Asynchronous calls</strong></dt>
<dd>The latest Erlang versions (R7B and later) has provision for
asynchronous function calls, using a thread pool provided by
Erlang. There is also a select call, that can be used for
asynchronous drivers.</dd>
<dt><strong><a name="multi_threading">Multi-threading</a></strong></dt>
<dd>
<p>A POSIX thread like API for multi-threading is provided. The
Erlang driver thread API only provide a subset of the functionality
provided by the POSIX thread API. The subset provided is
more or less the basic functionality needed for multi-threaded
programming:
</p>
<ul>
<li><span class="bold_code"><a href="#ErlDrvTid">Threads</a></span></li>
<li><span class="bold_code"><a href="#ErlDrvMutex">Mutexes</a></span></li>
<li><span class="bold_code"><a href="#ErlDrvCond">Condition variables</a></span></li>
<li><span class="bold_code"><a href="#ErlDrvRWLock">Read/Write locks</a></span></li>
<li><span class="bold_code"><a href="#ErlDrvTSDKey">Thread specific data</a></span></li>
</ul>
<p>The Erlang driver thread API can be used in conjunction with
the POSIX thread API on UN-ices and with the Windows native thread
API on Windows. The Erlang driver thread API has the advantage of
being portable, but there might exist situations where you want to
use functionality from the POSIX thread API or the Windows
native thread API.
</p>
<p>The Erlang driver thread API only returns error codes when it is
reasonable to recover from an error condition. If it isn't reasonable
to recover from an error condition, the whole runtime system is
terminated. For example, if a create mutex operation fails, an error
code is returned, but if a lock operation on a mutex fails, the
whole runtime system is terminated.
</p>
<p>Note that there exists no "condition variable wait with timeout" in
the Erlang driver thread API. This is due to issues with
<span class="code">pthread_cond_timedwait()</span>. When the system clock suddenly
is changed, it isn't always guaranteed that you will wake up from
the call as expected. An Erlang runtime system has to be able to
cope with sudden changes of the system clock. Therefore, we have
omitted it from the Erlang driver thread API. In the Erlang driver
case, timeouts can and should be handled with the timer functionality
of the Erlang driver API.
</p>
<p>In order for the Erlang driver thread API to function, thread
support has to be enabled in the runtime system. An Erlang driver
can check if thread support is enabled by use of
<span class="bold_code"><a href="#driver_system_info">driver_system_info()</a></span>.
Note that some functions in the Erlang driver API are thread-safe
only when the runtime system has SMP support, also this
information can be retrieved via
<span class="bold_code"><a href="#driver_system_info">driver_system_info()</a></span>.
Also note that a lot of functions in the Erlang driver API are
<strong>not</strong> thread-safe regardless of whether SMP support is
enabled or not. If a function isn't documented as thread-safe it
is <strong>not</strong> thread-safe.
</p>
<p><strong>NOTE</strong>: When executing in an emulator thread, it is
<strong>very important</strong> that you unlock <strong>all</strong> locks you
have locked before letting the thread out of your control;
otherwise, you are <strong>very likely</strong> to deadlock the whole
emulator. If you need to use thread specific data in an emulator
thread, only have the thread specific data set while the thread is
under your control, and clear the thread specific data before
you let the thread out of your control.
</p>
<p>In the future there will probably be debug functionality
integrated with the Erlang driver thread API. All functions
that create entities take a <span class="code">name</span> argument. Currently
the <span class="code">name</span> argument is unused, but it will be used when
the debug functionality has been implemented. If you name all
entities created well, the debug functionality will be able
to give you better error reports.
</p>
</dd>
<dt><strong>Adding / removing drivers</strong></dt>
<dd><p>A driver can add and later remove drivers.</p></dd>
<dt><strong>Monitoring processes</strong></dt>
<dd><p>A driver can monitor a process that does not own a port.</p></dd>
<dt><strong><a name="version_management">Version management</a></strong></dt>
<dd>
<p>Version management is enabled for drivers that have set the
<span class="bold_code"><a href="driver_entry.html#extended_marker">extended_marker</a></span>
field of their
<span class="bold_code"><a href="driver_entry.html">driver_entry</a></span>
to <span class="code">ERL_DRV_EXTENDED_MARKER</span>. <span class="code">erl_driver.h</span> defines
<span class="code">ERL_DRV_EXTENDED_MARKER</span>,
<span class="code">ERL_DRV_EXTENDED_MAJOR_VERSION</span>, and
<span class="code">ERL_DRV_EXTENDED_MINOR_VERSION</span>.
<span class="code">ERL_DRV_EXTENDED_MAJOR_VERSION</span> will be incremented when
driver incompatible changes are made to the Erlang runtime
system. Normally it will suffice to recompile drivers when the
<span class="code">ERL_DRV_EXTENDED_MAJOR_VERSION</span> has changed, but it
could, under rare circumstances, mean that drivers have to
be slightly modified. If so, this will of course be documented.
<span class="code">ERL_DRV_EXTENDED_MINOR_VERSION</span> will be incremented when
new features are added. The runtime system uses the minor version
of the driver to determine what features to use.
The runtime system will refuse to load a driver if the major
versions differ, or if the major versions are equal and the
minor version used by the driver is greater than the one used
by the runtime system.</p>
<p>The emulator will refuse to load a driver that does not use
the extended driver interface since,
to allow for 64-bit capable drivers,
incompatible type changes for the callbacks
<span class="bold_code"><a href="driver_entry.html#output">output</a></span>,
<span class="bold_code"><a href="driver_entry.html#control">control</a></span> and
<span class="bold_code"><a href="driver_entry.html#call">call</a></span>
were introduced in release R15B. A driver written
with the old types would compile with warnings and when
called return garbage sizes to the emulator causing it
to read random memory and create huge incorrect result blobs.</p>
<p>Therefore it is not enough to just recompile drivers written with
version management for pre-R15B types; the types have to be changed
in the driver suggesting other rewrites especially regarding
size variables. Investigate all warnings when recompiling!</p>
<p>Also, the API driver functions <span class="code">driver_output*</span>,
<span class="code">driver_vec_to_buf</span>, <span class="code">driver_alloc/realloc*</span>
and the <span class="code">driver_*</span> queue functions were changed to have
larger length arguments and return values. This is a
lesser problem since code that passes smaller types
will get them auto converted in the calls and as long as
the driver does not handle sizes that overflow an <span class="code">int</span>
all will work as before.</p>
</dd>
</dl>
</div>
<h3><a name="id161359">
REWRITES FOR 64-BIT DRIVER INTERFACE
</a></h3>
<div class="REFBODY">
<a name="rewrites_for_64_bits"></a>
<p>
For erts-5.9 two new integer types
<span class="bold_code"><a href="#ErlDrvSizeT">ErlDrvSizeT</a></span> and
<span class="bold_code"><a href="#ErlDrvSSizeT">ErlDrvSSizeT</a></span>
were introduced that can hold 64-bit sizes if necessary.
</p>
<p>
To not update a driver and just recompile it probably works
when building for a 32-bit machine creating a false sense of security.
Hopefully that will generate many important warnings.
But when recompiling the same driver later on for a 64-bit machine
there <strong>will</strong> be warnings and almost certainly crashes.
So it is a BAD idea to postpone updating the driver and
not fixing the warnings!
</p>
<p>
When recompiling with <span class="code">gcc</span> use the <span class="code">-Wstrict-prototypes</span>
flag to get better warnings. Try to find a similar flag if you
are using some other compiler.
</p>
<p>
Here follows a checklist for rewriting a pre erts-5.9 driver,
most important first.
</p>
<dl>
<dt><strong>Return types for driver callbacks</strong></dt>
<dd>
<p>
Rewrite driver callback
<span class="code"><span class="bold_code"><a href="driver_entry.html#control">control</a></span></span>
to use return type <span class="code">ErlDrvSSizeT</span> instead of <span class="code">int</span>.
</p>
<p>
Rewrite driver callback
<span class="code"><span class="bold_code"><a href="driver_entry.html#call">call</a></span></span>
to use return type <span class="code">ErlDrvSSizeT</span> instead of <span class="code">int</span>.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
These changes are essential to not crash the emulator
or worse cause malfunction.
Without them a driver may return garbage in the high 32 bits
to the emulator causing it to build a huge result from random
bytes either crashing on memory allocation or succeeding with
a random result from the driver call.
</p>
</p></div>
</div>
</dd>
<dt><strong>Arguments to driver callbacks</strong></dt>
<dd>
<p>
Driver callback
<span class="code"><span class="bold_code"><a href="driver_entry.html#output">output</a></span></span>
now gets <span class="code">ErlDrvSizeT</span> as 3rd argument instead
of previously <span class="code">int</span>.
</p>
<p>
Driver callback
<span class="code"><span class="bold_code"><a href="driver_entry.html#control">control</a></span></span>
now gets <span class="code">ErlDrvSizeT</span> as 4th and 6th arguments instead
of previously <span class="code">int</span>.
</p>
<p>
Driver callback
<span class="code"><span class="bold_code"><a href="driver_entry.html#call">call</a></span></span>
now gets <span class="code">ErlDrvSizeT</span> as 4th and 6th arguments instead
of previously <span class="code">int</span>.
</p>
<p>
Sane compiler's calling conventions probably make these changes
necessary only for a driver to handle data chunks that require
64-bit size fields (mostly larger than 2 GB since that is what
an <span class="code">int</span> of 32 bits can hold). But it is possible to think
of non-sane calling conventions that would make the driver
callbacks mix up the arguments causing malfunction.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
The argument type change is from signed to unsigned which
may cause problems for e.g. loop termination conditions or
error conditions if you just change the types all over the place.
</p>
</p></div>
</div>
</dd>
<dt><strong>Larger <span class="code">size</span> field in <span class="code">ErlIOVec</span></strong></dt>
<dd>
<p>
The <span class="code">size</span> field in
<span class="bold_code"><a href="#ErlIOVec"><span class="code">ErlIOVec</span></a></span>
has been changed to <span class="code">ErlDrvSizeT</span> from <span class="code">int</span>.
Check all code that use that field.
</p>
<p>
Automatic type casting probably makes these changes necessary only
for a driver that encounters sizes larger than 32 bits.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
The <span class="code">size</span> field changed from signed to unsigned which
may cause problems for e.g. loop termination conditions or
error conditions if you just change the types all over the place.
</p>
</p></div>
</div>
</dd>
<dt><strong>Arguments and return values in the driver API</strong></dt>
<dd>
<p>
Many driver API functions have changed argument type
and/or return value to <span class="code">ErlDrvSizeT</span> from mostly <span class="code">int</span>.
Automatic type casting probably makes these changes necessary only
for a driver that encounters sizes larger than 32 bits.
</p>
<dl>
<dt><strong><span class="bold_code"><a href="#driver_output">driver_output</a></span></strong></dt>
<dd>3rd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_output2">driver_output2</a></span></strong></dt>
<dd>3rd and 5th arguments</dd>
<dt><strong>
<span class="bold_code"><a href="#driver_output_binary">driver_output_binary</a></span>
</strong></dt>
<dd>3rd 5th and 6th arguments</dd>
<dt><strong><span class="bold_code"><a href="#driver_outputv">driver_outputv</a></span></strong></dt>
<dd>3rd and 5th arguments</dd>
<dt><strong>
<span class="bold_code"><a href="#driver_vec_to_buf">driver_vec_to_buf</a></span>
</strong></dt>
<dd>3rd argument and return value</dd>
<dt><strong><span class="bold_code"><a href="#driver_alloc">driver_alloc</a></span></strong></dt>
<dd>1st argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_realloc">driver_realloc</a></span></strong></dt>
<dd>2nd argument</dd>
<dt><strong>
<span class="bold_code"><a href="#driver_alloc_binary">driver_alloc_binary</a></span>
</strong></dt>
<dd>1st argument</dd>
<dt><strong>
<span class="bold_code"><a href="#driver_realloc_binary">driver_realloc_binary</a></span>
</strong></dt>
<dd>2nd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_enq">driver_enq</a></span></strong></dt>
<dd>3rd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_pushq">driver_pushq</a></span></strong></dt>
<dd>3rd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_deq">driver_deq</a></span></strong></dt>
<dd>2nd argument and return value</dd>
<dt><strong><span class="bold_code"><a href="#driver_sizeq">driver_sizeq</a></span></strong></dt>
<dd>return value</dd>
<dt><strong><span class="bold_code"><a href="#driver_enq_bin">driver_enq_bin</a></span></strong></dt>
<dd>3rd and 4th argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_pushq_bin">driver_pushq_bin</a></span></strong></dt>
<dd>3rd and 4th argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_enqv">driver_enqv</a></span></strong></dt>
<dd>3rd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_pushqv">driver_pushqv</a></span></strong></dt>
<dd>3rd argument</dd>
<dt><strong><span class="bold_code"><a href="#driver_peekqv">driver_peekqv</a></span></strong></dt>
<dd>return value</dd>
</dl>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
This is a change from signed to unsigned which
may cause problems for e.g. loop termination conditions and
error conditions if you just change the types all over the place.
</p>
</p></div>
</div>
</dd>
</dl>
</div>
<h3><a name="id161843">DATA TYPES</a></h3>
<div class="REFBODY">
<dl>
<dt><strong><a name="ErlDrvSizeT"></a>ErlDrvSizeT</strong></dt>
<dd><p>An unsigned integer type to be used as <span class="code">size_t</span></p></dd>
<dt><strong><a name="ErlDrvSSizeT"></a>ErlDrvSSizeT</strong></dt>
<dd><p>A signed integer type the size of <span class="code">ErlDrvSizeT</span></p></dd>
<dt><strong><a name="ErlDrvSysInfo"></a>ErlDrvSysInfo</strong></dt>
<dd>
<p></p>
<div class="example"><pre>
typedef struct ErlDrvSysInfo {
int driver_major_version;
int driver_minor_version;
char *erts_version;
char *otp_release;
int thread_support;
int smp_support;
int async_threads;
int scheduler_threads;
int nif_major_version;
int nif_minor_version;
} ErlDrvSysInfo;
</pre></div>
<p>
The <span class="code">ErlDrvSysInfo</span> structure is used for storage of
information about the Erlang runtime system.
<span class="bold_code"><a href="#driver_system_info">driver_system_info()</a></span>
will write the system information when passed a reference to
a <span class="code">ErlDrvSysInfo</span> structure. A description of the
fields in the structure follows:
</p>
<dl>
<dt><strong><span class="code">driver_major_version</span></strong></dt>
<dd>The value of
<span class="bold_code"><a href="#version_management">ERL_DRV_EXTENDED_MAJOR_VERSION</a></span>
when the runtime system was compiled. This value is the same
as the value of
<span class="bold_code"><a href="#version_management">ERL_DRV_EXTENDED_MAJOR_VERSION</a></span>
used when compiling the driver; otherwise, the runtime system
would have refused to load the driver.
</dd>
<dt><strong><span class="code">driver_minor_version</span></strong></dt>
<dd>The value of
<span class="bold_code"><a href="#version_management">ERL_DRV_EXTENDED_MINOR_VERSION</a></span>
when the runtime system was compiled. This value might differ
from the value of
<span class="bold_code"><a href="#version_management">ERL_DRV_EXTENDED_MINOR_VERSION</a></span>
used when compiling the driver.
</dd>
<dt><strong><span class="code">erts_version</span></strong></dt>
<dd>A string containing the version number of the runtime system
(the same as returned by
<span class="bold_code"><a href="erlang.html#system_info_version">erlang:system_info(version)</a></span>).
</dd>
<dt><strong><span class="code">otp_release</span></strong></dt>
<dd>A string containing the OTP release number
(the same as returned by
<span class="bold_code"><a href="erlang.html#system_info_otp_release">erlang:system_info(otp_release)</a></span>).
</dd>
<dt><strong><span class="code">thread_support</span></strong></dt>
<dd>A value <span class="code">!= 0</span> if the runtime system has thread support;
otherwise, <span class="code">0</span>.
</dd>
<dt><strong><span class="code">smp_support</span></strong></dt>
<dd>A value <span class="code">!= 0</span> if the runtime system has SMP support;
otherwise, <span class="code">0</span>.
</dd>
<dt><strong><span class="code">async_threads</span></strong></dt>
<dd>The number of async threads in the async thread pool used
by <span class="bold_code"><a href="#driver_async">driver_async()</a></span>
(the same as returned by
<span class="bold_code"><a href="erlang.html#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</a></span>).
</dd>
<dt><strong><span class="code">scheduler_threads</span></strong></dt>
<dd>The number of scheduler threads used by the runtime system
(the same as returned by
<span class="bold_code"><a href="erlang.html#system_info_schedulers">erlang:system_info(schedulers)</a></span>).
</dd>
<dt><strong><span class="code">nif_major_version</span></strong></dt>
<dd>The value of <span class="code">ERL_NIF_MAJOR_VERSION</span> when the runtime system was compiled.
</dd>
<dt><strong><span class="code">nif_minor_version</span></strong></dt>
<dd>The value of <span class="code">ERL_NIF_MINOR_VERSION</span> when the runtime system was compiled.
</dd>
</dl>
</dd>
<dt><strong><a name="ErlDrvBinary"></a>ErlDrvBinary</strong></dt>
<dd>
<p></p>
<div class="example"><pre>
typedef struct ErlDrvBinary {
ErlDrvSint orig_size;
char orig_bytes[];
} ErlDrvBinary;
</pre></div>
<p>The <span class="code">ErlDrvBinary</span> structure is a binary, as sent
between the emulator and the driver. All binaries are
reference counted; when <span class="code">driver_binary_free</span> is called,
the reference count is decremented, when it reaches zero,
the binary is deallocated. The <span class="code">orig_size</span> is the size
of the binary, and <span class="code">orig_bytes</span> is the buffer. The
<span class="code">ErlDrvBinary</span> does not have a fixed size, its size is
<span class="code">orig_size + 2 * sizeof(int)</span>.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>The <span class="code">refc</span> field has been removed. The reference count of
an <span class="code">ErlDrvBinary</span> is now stored elsewhere. The
reference count of an <span class="code">ErlDrvBinary</span> can be accessed via
<span class="bold_code"><a href="#driver_binary_get_refc">driver_binary_get_refc()</a></span>,
<span class="bold_code"><a href="#driver_binary_inc_refc">driver_binary_inc_refc()</a></span>,
and
<span class="bold_code"><a href="#driver_binary_dec_refc">driver_binary_dec_refc()</a></span>.</p>
</p></div>
</div>
<p>Some driver calls, such as <span class="code">driver_enq_binary</span>,
increment the driver reference count, and others, such as
<span class="code">driver_deq</span> decrement it.</p>
<p>Using a driver binary instead of a normal buffer, is often
faster, since the emulator doesn't need to copy the data,
only the pointer is used.</p>
<p>A driver binary allocated in the driver, with
<span class="code">driver_alloc_binary</span>, should be freed in the driver (unless otherwise stated),
with <span class="code">driver_free_binary</span>. (Note that this doesn't
necessarily deallocate it, if the driver is still referred
in the emulator, the ref-count will not go to zero.)</p>
<p>Driver binaries are used in the <span class="code">driver_output2</span> and
<span class="code">driver_outputv</span> calls, and in the queue. Also the
driver call-back <span class="bold_code"><a href="driver_entry.html#outputv">outputv</a></span> uses driver
binaries.</p>
<p>If the driver for some reason or another, wants to keep a
driver binary around, in a static variable for instance, the
reference count should be incremented,
and the binary can later be freed in the <span class="bold_code"><a href="driver_entry.html#stop">stop</a></span> call-back, with
<span class="code">driver_free_binary</span>.</p>
<p>Note that since a driver binary is shared by the driver and
the emulator, a binary received from the emulator or sent to
the emulator, must not be changed by the driver.</p>
<p>Since erts version 5.5 (OTP release R11B), orig_bytes is
guaranteed to be properly aligned for storage of an array of
doubles (usually 8-byte aligned).</p>
</dd>
<dt><strong>ErlDrvData</strong></dt>
<dd>
<p>The <span class="code">ErlDrvData</span> is a handle to driver-specific data,
passed to the driver call-backs. It is a pointer, and is
most often type casted to a specific pointer in the driver.</p>
</dd>
<dt><strong>SysIOVec</strong></dt>
<dd>
<p>This is a system I/O vector, as used by <span class="code">writev</span> on
unix and <span class="code">WSASend</span> on Win32. It is used in
<span class="code">ErlIOVec</span>.</p>
</dd>
<dt><strong><a name="ErlIOVec"></a>ErlIOVec</strong></dt>
<dd>
<p></p>
<div class="example"><pre>
typedef struct ErlIOVec {
int vsize;
ErlDrvSizeT size;
SysIOVec* iov;
ErlDrvBinary** binv;
} ErlIOVec;
</pre></div>
<p>The I/O vector used by the emulator and drivers, is a list
of binaries, with a <span class="code">SysIOVec</span> pointing to the buffers
of the binaries. It is used in <span class="code">driver_outputv</span> and the
<span class="bold_code"><a href="driver_entry.html#outputv">outputv</a></span>
driver call-back. Also, the driver queue is an
<span class="code">ErlIOVec</span>.</p>
</dd>
<dt><strong>ErlDrvMonitor</strong></dt>
<dd>
<p>When a driver creates a monitor for a process, a
<span class="code">ErlDrvMonitor</span> is filled in. This is an opaque
data-type which can be assigned to but not compared without
using the supplied compare function (i.e. it behaves like a struct).</p>
<p>The driver writer should provide the memory for storing the
monitor when calling <span class="bold_code"><a href="#driver_monitor_process">driver_monitor_process</a></span>. The
address of the data is not stored outside of the driver, so
the <span class="code">ErlDrvMonitor</span> can be used as any other datum, it
can be copied, moved in memory, forgotten etc.</p>
</dd>
<dt><strong><a name="ErlDrvNowData"></a>ErlDrvNowData</strong></dt>
<dd>
<p>The <span class="code">ErlDrvNowData</span> structure holds a timestamp
consisting of three values measured from some arbitrary
point in the past. The three structure members are:</p>
<dl>
<dt><strong>megasecs</strong></dt>
<dd>The number of whole megaseconds elapsed since the arbitrary
point in time</dd>
<dt><strong>secs</strong></dt>
<dd>The number of whole seconds elapsed since the arbitrary
point in time</dd>
<dt><strong>microsecs</strong></dt>
<dd>The number of whole microseconds elapsed since the arbitrary
point in time</dd>
</dl>
</dd>
<dt><strong><a name="ErlDrvPDL"></a>ErlDrvPDL</strong></dt>
<dd>
<p>If certain port specific data have to be accessed from other
threads than those calling the driver call-backs, a port data lock
can be used in order to synchronize the operations on the data.
Currently, the only port specific data that the emulator
associates with the port data lock is the driver queue.</p>
<p>Normally a driver instance does not have a port data lock. If
the driver instance wants to use a port data lock, it has to
create the port data lock by calling
<span class="bold_code"><a href="#driver_pdl_create">driver_pdl_create()</a></span>.
<strong>NOTE</strong>: Once the port data lock has been created, every
access to data associated with the port data lock has to be done
while having the port data lock locked. The port data lock is
locked, and unlocked, respectively, by use of
<span class="bold_code"><a href="#driver_pdl_lock">driver_pdl_lock()</a></span>, and
<span class="bold_code"><a href="#driver_pdl_unlock">driver_pdl_unlock()</a></span>.</p>
<p>A port data lock is reference counted, and when the reference
count reaches zero, it will be destroyed. The emulator will at
least increment the reference count once when the lock is
created and decrement it once when the port associated with
the lock terminates. The emulator will also increment the
reference count when an async job is enqueued and decrement
it after an async job has been invoked, or canceled. Besides
this, it is the responsibility of the driver to ensure that
the reference count does not reach zero before the last use
of the lock by the driver has been made. The reference count
can be read, incremented, and decremented, respectively, by
use of
<span class="bold_code"><a href="#driver_pdl_get_refc">driver_pdl_get_refc()</a></span>,
<span class="bold_code"><a href="#driver_pdl_inc_refc">driver_pdl_inc_refc()</a></span>, and
<span class="bold_code"><a href="#driver_pdl_dec_refc">driver_pdl_dec_refc()</a></span>.</p>
</dd>
<dt><strong><a name="ErlDrvTid"></a>ErlDrvTid</strong></dt>
<dd>
<p>Thread identifier.</p>
<p>See also:
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_thread_exit">erl_drv_thread_exit()</a></span>,
<span class="bold_code"><a href="#erl_drv_thread_join">erl_drv_thread_join()</a></span>,
<span class="bold_code"><a href="#erl_drv_thread_self">erl_drv_thread_self()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_equal_tids">erl_drv_equal_tids()</a></span>.
</p>
</dd>
<dt><strong><a name="ErlDrvThreadOpts"></a>ErlDrvThreadOpts</strong></dt>
<dd>
<p></p>
<div class="example"><pre>
int suggested_stack_size;
</pre></div>
<p>Thread options structure passed to
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>.
Currently the following fields exist:
</p>
<dl>
<dt><strong>suggested_stack_size</strong></dt>
<dd>A suggestion, in kilo-words, on how large a stack to use. A value less
than zero means default size.
</dd>
</dl>
<p>See also:
<span class="bold_code"><a href="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_thread_opts_destroy">erl_drv_thread_opts_destroy()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>.
</p>
</dd>
<dt><strong><a name="ErlDrvMutex"></a>ErlDrvMutex</strong></dt>
<dd>
<p>Mutual exclusion lock. Used for synchronizing access to shared data.
Only one thread at a time can lock a mutex.
</p>
<p>See also:
<span class="bold_code"><a href="#erl_drv_mutex_create">erl_drv_mutex_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_mutex_destroy">erl_drv_mutex_destroy()</a></span>,
<span class="bold_code"><a href="#erl_drv_mutex_lock">erl_drv_mutex_lock()</a></span>,
<span class="bold_code"><a href="#erl_drv_mutex_trylock">erl_drv_mutex_trylock()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_mutex_unlock">erl_drv_mutex_unlock()</a></span>.
</p>
</dd>
<dt><strong><a name="ErlDrvCond"></a>ErlDrvCond</strong></dt>
<dd>
<p>Condition variable. Used when threads need to wait for a specific
condition to appear before continuing execution. Condition variables
need to be used with associated mutexes.
</p>
<p>See also:
<span class="bold_code"><a href="#erl_drv_cond_create">erl_drv_cond_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_cond_destroy">erl_drv_cond_destroy()</a></span>,
<span class="bold_code"><a href="#erl_drv_cond_signal">erl_drv_cond_signal()</a></span>,
<span class="bold_code"><a href="#erl_drv_cond_broadcast">erl_drv_cond_broadcast()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_cond_wait">erl_drv_cond_wait()</a></span>.
</p>
</dd>
<dt><strong><a name="ErlDrvRWLock"></a>ErlDrvRWLock</strong></dt>
<dd>
<p>Read/write lock. Used to allow multiple threads to read shared data
while only allowing one thread to write the same data. Multiple threads
can read lock an rwlock at the same time, while only one thread can
read/write lock an rwlock at a time.
</p>
<p>See also:
<span class="bold_code"><a href="#erl_drv_rwlock_create">erl_drv_rwlock_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_destroy">erl_drv_rwlock_destroy()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_rlock">erl_drv_rwlock_rlock()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_tryrlock">erl_drv_rwlock_tryrlock()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_runlock">erl_drv_rwlock_runlock()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_rwlock">erl_drv_rwlock_rwlock()</a></span>,
<span class="bold_code"><a href="#erl_drv_rwlock_tryrwlock">erl_drv_rwlock_tryrwlock()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_rwlock_rwunlock">erl_drv_rwlock_rwunlock()</a></span>.
</p>
</dd>
<dt><strong><a name="ErlDrvTSDKey"></a>ErlDrvTSDKey</strong></dt>
<dd>
<p>Key which thread specific data can be associated with.</p>
<p>See also:
<span class="bold_code"><a href="#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</a></span>,
<span class="bold_code"><a href="#erl_drv_tsd_key_destroy">erl_drv_tsd_key_destroy()</a></span>,
<span class="bold_code"><a href="#erl_drv_tsd_set">erl_drv_tsd_set()</a></span>,
and
<span class="bold_code"><a href="#erl_drv_tsd_get">erl_drv_tsd_get()</a></span>.
</p>
</dd>
</dl>
</div>
<h3>EXPORTS</h3>
<p><a name="driver_system_info"><span class="bold_code">void driver_system_info(ErlDrvSysInfo *sys_info_ptr, size_t size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_system_info"></a>
<p>This function will write information about the Erlang runtime
system into the
<span class="bold_code"><a href="#ErlDrvSysInfo">ErlDrvSysInfo</a></span>
structure referred to by the first argument. The second
argument should be the size of the
<span class="bold_code"><a href="#ErlDrvSysInfo">ErlDrvSysInfo</a></span>
structure, i.e., <span class="code">sizeof(ErlDrvSysInfo)</span>.</p>
<p>See the documentation of the
<span class="bold_code"><a href="#ErlDrvSysInfo">ErlDrvSysInfo</a></span>
structure for information about specific fields.</p>
</p></div>
<p><a name="driver_output"><span class="bold_code">int driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_output"></a>
<p>The <span class="code">driver_output</span> function is used to send data from
the driver up to the emulator. The data will be received as
terms or binary data, depending on how the driver port was
opened.</p>
<p>The data is queued in the port owner process' message
queue. Note that this does not yield to the emulator. (Since
the driver and the emulator run in the same thread.)</p>
<p>The parameter <span class="code">buf</span> points to the data to send, and
<span class="code">len</span> is the number of bytes.</p>
<p>The return value for all output functions is 0. (Unless the
driver is used for distribution, in which case it can fail
and return -1. For normal use, the output function always
returns 0.)</p>
</p></div>
<p><a name="driver_output2"><span class="bold_code">int driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_output2"></a>
<p>The <span class="code">driver_output2</span> function first sends <span class="code">hbuf</span>
(length in <span class="code">hlen</span>) data as a list, regardless of port
settings. Then <span class="code">buf</span> is sent as a binary or list.
E.g. if <span class="code">hlen</span> is 3 then the port owner process will
receive <span class="code">[H1, H2, H3 | T]</span>.</p>
<p>The point of sending data as a list header, is to facilitate
matching on the data received.</p>
<p>The return value is 0 for normal use.</p>
</p></div>
<p><a name="driver_output_binary"><span class="bold_code">int driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_output_binary"></a>
<p>This function sends data to port owner process from a
driver binary, it has a header buffer (<span class="code">hbuf</span>
and <span class="code">hlen</span>) just like <span class="code">driver_output2</span>. The
<span class="code">hbuf</span> parameter can be <span class="code">NULL</span>.</p>
<p>The parameter <span class="code">offset</span> is an offset into the binary and
<span class="code">len</span> is the number of bytes to send.</p>
<p>Driver binaries are created with <span class="code">driver_alloc_binary</span>.</p>
<p>The data in the header is sent as a list and the binary as
an Erlang binary in the tail of the list.</p>
<p>E.g. if <span class="code">hlen</span> is 2, then the port owner process will
receive <span class="code">[H1, H2 | <<T>>]</span>.</p>
<p>The return value is 0 for normal use.</p>
<p>Note that, using the binary syntax in Erlang, the driver
application can match the header directly from the binary,
so the header can be put in the binary, and hlen can be set
to 0.</p>
</p></div>
<p><a name="driver_outputv"><span class="bold_code">int driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen, ErlIOVec *ev, ErlDrvSizeT skip)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_outputv"></a>
<p>This function sends data from an IO vector, <span class="code">ev</span>, to
the port owner process. It has a header buffer (<span class="code">hbuf</span>
and <span class="code">hlen</span>), just like <span class="code">driver_output2</span>.</p>
<p>The <span class="code">skip</span> parameter is a number of bytes to skip of
the <span class="code">ev</span> vector from the head.</p>
<p>You get vectors of <span class="code">ErlIOVec</span> type from the driver
queue (see below), and the <span class="bold_code"><a href="driver_entry.html#outputv">outputv</a></span> driver entry
function. You can also make them yourself, if you want to
send several <span class="code">ErlDrvBinary</span> buffers at once. Often
it is faster to use <span class="code">driver_output</span> or
<span class="code">driver_output_binary</span>.</p>
<p>E.g. if <span class="code">hlen</span> is 2 and <span class="code">ev</span> points to an array of
three binaries, the port owner process will receive <span class="code">[H1, H2, <<B1>>, <<B2>> | <<B3>>]</span>.</p>
<p>The return value is 0 for normal use.</p>
<p>The comment for <span class="code">driver_output_binary</span> applies for
<span class="code">driver_outputv</span> too.</p>
</p></div>
<p><a name="driver_vec_to_buf"><span class="bold_code">ErlDrvSizeT driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_vec_to_buf"></a>
<p>This function collects several segments of data, referenced
by <span class="code">ev</span>, by copying them in order to the buffer
<span class="code">buf</span>, of the size <span class="code">len</span>.</p>
<p>If the data is to be sent from the driver to the port owner
process, it is faster to use <span class="code">driver_outputv</span>.</p>
<p>The return value is the space left in the buffer, i.e. if
the <span class="code">ev</span> contains less than <span class="code">len</span> bytes it's the
difference, and if <span class="code">ev</span> contains <span class="code">len</span> bytes or
more, it's 0. This is faster if there is more than one header byte,
since the binary syntax can construct integers directly from
the binary.</p>
</p></div>
<p><a name="driver_set_timer"><span class="bold_code">int driver_set_timer(ErlDrvPort port, unsigned long time)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_set_timer"></a>
<p>This function sets a timer on the driver, which will count
down and call the driver when it is timed out. The
<span class="code">time</span> parameter is the time in milliseconds before the
timer expires.</p>
<p>When the timer reaches 0 and expires, the driver entry
function <span class="bold_code"><a href="driver_entry.html#timeout">timeout</a></span> is called.</p>
<p>Note that there is only one timer on each driver instance;
setting a new timer will replace an older one.</p>
<p>Return value is 0 (-1 only when the <span class="code">timeout</span> driver
function is <span class="code">NULL</span>).</p>
</p></div>
<p><a name="driver_cancel_timer"><span class="bold_code">int driver_cancel_timer(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_cancel_timer"></a>
<p>This function cancels a timer set with
<span class="code">driver_set_timer</span>.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_read_timer"><span class="bold_code">int driver_read_timer(ErlDrvPort port, unsigned long *time_left)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_read_timer"></a>
<p>This function reads the current time of a timer, and places
the result in <span class="code">time_left</span>. This is the time in
milliseconds, before the timeout will occur.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_get_now"><span class="bold_code">int driver_get_now(ErlDrvNowData *now)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_get_now"></a>
<p>This function reads a timestamp into the memory pointed to by
the parameter <span class="code">now</span>. See the description of <span class="bold_code"><a href="#ErlDrvNowData">ErlDrvNowData</a></span> for
specification of its fields. </p>
<p>The return value is 0 unless the <span class="code">now</span> pointer is not
valid, in which case it is < 0. </p>
</p></div>
<p><a name="driver_select"><span class="bold_code">int driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_select"></a>
<p>This function is used by drivers to provide the emulator with
events to check for. This enables the emulator to call the driver
when something has happened asynchronously.</p>
<p>The <span class="code">event</span> argument identifies an OS-specific event object.
On Unix systems, the functions <span class="code">select</span>/<span class="code">poll</span> are used. The
event object must be a socket or pipe (or other object that
<span class="code">select</span>/<span class="code">poll</span> can use).
On windows, the Win32 API function <span class="code">WaitForMultipleObjects</span>
is used. This places other restrictions on the event object.
Refer to the Win32 SDK documentation.</p>
<p>The <span class="code">on</span> parameter should be <span class="code">1</span> for setting events
and <span class="code">0</span> for clearing them.</p>
<p>The <span class="code">mode</span> argument is a bitwise-or combination of
<span class="code">ERL_DRV_READ</span>, <span class="code">ERL_DRV_WRITE</span> and <span class="code">ERL_DRV_USE</span>.
The first two specify whether to wait for read events and/or write
events. A fired read event will call
<span class="bold_code"><a href="driver_entry.html#ready_input">ready_input</a></span>
while a fired write event will call
<span class="bold_code"><a href="driver_entry.html#ready_output">ready_output</a></span>.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Some OS (Windows) do not differentiate between read and write events.
The call-back for a fired event then only depends on the value of <span class="code">mode</span>.</p>
</p></div>
</div>
<p><span class="code">ERL_DRV_USE</span> specifies if we are using the event object or if we want to close it.
On an emulator with SMP support, it is not safe to clear all events
and then close the event object after <span class="code">driver_select</span> has
returned. Another thread may still be using the event object
internally. To safely close an event object call
<span class="code">driver_select</span> with <span class="code">ERL_DRV_USE</span> and <span class="code">on==0</span>. That
will clear all events and then call
<span class="bold_code"><a href="driver_entry.html#stop_select">stop_select</a></span>
when it is safe to close the event object.
<span class="code">ERL_DRV_USE</span> should be set together with the first event
for an event object. It is harmless to set <span class="code">ERL_DRV_USE</span>
even though it already has been done. Clearing all events but keeping
<span class="code">ERL_DRV_USE</span> set will indicate that we are using the event
object and probably will set events for it again.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>ERL_DRV_USE was added in OTP release R13. Old drivers will still work
as before. But it is recommended to update them to use <span class="code">ERL_DRV_USE</span> and
<span class="code">stop_select</span> to make sure that event objects are closed in a safe way.</p>
</p></div>
</div>
<p>The return value is 0 (failure, -1, only if the
<span class="code">ready_input</span>/<span class="code">ready_output</span> is
<span class="code">NULL</span>).</p>
</p></div>
<p><a name="driver_alloc"><span class="bold_code">void *driver_alloc(ErlDrvSizeT size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_alloc"></a>
<p>This function allocates a memory block of the size specified
in <span class="code">size</span>, and returns it. This only fails on out of
memory, in that case <span class="code">NULL</span> is returned. (This is most
often a wrapper for <span class="code">malloc</span>).</p>
<p>Memory allocated must be explicitly freed with a corresponding
call to <span class="code">driver_free</span> (unless otherwise stated).</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_realloc"><span class="bold_code">void *driver_realloc(void *ptr, ErlDrvSizeT size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_realloc"></a>
<p>This function resizes a memory block, either in place, or by
allocating a new block, copying the data and freeing the old
block. A pointer is returned to the reallocated memory. On
failure (out of memory), <span class="code">NULL</span> is returned. (This is
most often a wrapper for <span class="code">realloc</span>.)</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_free"><span class="bold_code">void driver_free(void *ptr)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_free"></a>
<p>This function frees the memory pointed to by <span class="code">ptr</span>. The
memory should have been allocated with
<span class="code">driver_alloc</span>. All allocated memory should be
deallocated, just once. There is no garbage collection in
drivers.</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_alloc_binary"><span class="bold_code">ErlDrvBinary *driver_alloc_binary(ErlDrvSizeT size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_alloc_binary"></a>
<p>This function allocates a driver binary with a memory block
of at least <span class="code">size</span> bytes, and returns a pointer to it,
or NULL on failure (out of memory). When a driver binary has
been sent to the emulator, it must not be altered. Every
allocated binary should be freed by a corresponding call to
<span class="code">driver_free_binary</span> (unless otherwise stated).</p>
<p>Note that a driver binary has an internal reference counter,
this means that calling <span class="code">driver_free_binary</span> it may not
actually dispose of it. If it's sent to the emulator, it may
be referenced there.</p>
<p>The driver binary has a field, <span class="code">orig_bytes</span>, which
marks the start of the data in the binary.</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_realloc_binary"><span class="bold_code">ErlDrvBinary *driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_realloc_binary"></a>
<p>This function resizes a driver binary, while keeping the
data. The resized driver binary is returned. On failure (out
of memory), <span class="code">NULL</span> is returned.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
</p></div>
<p><a name="driver_free_binary"><span class="bold_code">void driver_free_binary(ErlDrvBinary *bin)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_free_binary"></a>
<p>This function frees a driver binary <span class="code">bin</span>, allocated
previously with <span class="code">driver_alloc_binary</span>. Since binaries
in Erlang are reference counted, the binary may still be
around.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
</p></div>
<p><a name="driver_binary_get_refc"><span class="bold_code">long driver_binary_get_refc(ErlDrvBinary *bin)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_binary_get_refc"></a>
<p>Returns current reference count on <span class="code">bin</span>.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
</p></div>
<p><a name="driver_binary_inc_refc"><span class="bold_code">long driver_binary_inc_refc(ErlDrvBinary *bin)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_binary_inc_refc"></a>
<p>Increments the reference count on <span class="code">bin</span> and returns
the reference count reached after the increment.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
</p></div>
<p><a name="driver_binary_dec_refc"><span class="bold_code">long driver_binary_dec_refc(ErlDrvBinary *bin)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_binary_dec_refc"></a>
<p>Decrements the reference count on <span class="code">bin</span> and returns
the reference count reached after the decrement.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>You should normally decrement the reference count of a
driver binary by calling
<span class="bold_code"><a href="#driver_free_binary">driver_free_binary()</a></span>.
<span class="code">driver_binary_dec_refc()</span> does <strong>not</strong> free
the binary if the reference count reaches zero. <strong>Only</strong>
use <span class="code">driver_binary_dec_refc()</span> when you are sure
<strong>not</strong> to reach a reference count of zero.</p>
</p></div>
</div>
</p></div>
<p><a name="driver_enq"><span class="bold_code">int driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_enq"></a>
<p>This function enqueues data in the driver queue. The data in
<span class="code">buf</span> is copied (<span class="code">len</span> bytes) and placed at the
end of the driver queue. The driver queue is normally used
in a FIFO way.</p>
<p>The driver queue is available to queue output from the
emulator to the driver (data from the driver to the emulator
is queued by the emulator in normal erlang message
queues). This can be useful if the driver has to wait for
slow devices etc, and wants to yield back to the
emulator. The driver queue is implemented as an ErlIOVec.</p>
<p>When the queue contains data, the driver won't close, until
the queue is empty.</p>
<p>The return value is 0.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_pushq"><span class="bold_code">int driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pushq"></a>
<p>This function puts data at the head of the driver queue. The
data in <span class="code">buf</span> is copied (<span class="code">len</span> bytes) and placed
at the beginning of the queue.</p>
<p>The return value is 0.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_deq"><span class="bold_code">ErlDrvSizeT driver_deq(ErlDrvPort port, ErlDrvSizeT size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_deq"></a>
<p>This function dequeues data by moving the head pointer
forward in the driver queue by <span class="code">size</span> bytes. The data
in the queue will be deallocated.</p>
<p>The return value is the number of bytes remaining in the queue
or -1 on failure.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_sizeq"><span class="bold_code">ErlDrvSizeT driver_sizeq(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_sizeq"></a>
<p>This function returns the number of bytes currently in the
driver queue.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_enq_bin"><span class="bold_code">int driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_enq_bin"></a>
<p>This function enqueues a driver binary in the driver
queue. The data in <span class="code">bin</span> at <span class="code">offset</span> with length
<span class="code">len</span> is placed at the end of the queue. This function
is most often faster than <span class="code">driver_enq</span>, because the
data doesn't have to be copied.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_pushq_bin"><span class="bold_code">int driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pushq_bin"></a>
<p>This function puts data in the binary <span class="code">bin</span>, at
<span class="code">offset</span> with length <span class="code">len</span> at the head of the
driver queue. It is most often faster than
<span class="code">driver_pushq</span>, because the data doesn't have to be
copied.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_peekqv"><span class="bold_code">ErlDrvSizeT driver_peekqv(ErlDrvPort port, ErlIOVec *ev)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_peekqv"></a>
<p>
This function retrieves the driver queue into a supplied
<span class="code">ErlIOVec</span> <span class="code">ev</span>. It also returns the queue size.
This is one of two ways to get data out of the queue.
</p>
<p>
If <span class="code">ev</span> is <span class="code">NULL</span> all ones i.e. <span class="code">-1</span> type cast to
<span class="code">ErlDrvSizeT</span> is returned.
</p>
<p>Nothing is removed from the queue by this function, that must be done
with <span class="code">driver_deq</span>.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_peekq"><span class="bold_code">SysIOVec *driver_peekq(ErlDrvPort port, int *vlen)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_peekq"></a>
<p>This function retrieves the driver queue as a pointer to an
array of <span class="code">SysIOVec</span>s. It also returns the number of
elements in <span class="code">vlen</span>. This is one of two ways to get data
out of the queue.</p>
<p>Nothing is removed from the queue by this function, that must be done
with <span class="code">driver_deq</span>.</p>
<p>The returned array is suitable to use with the Unix system
call <span class="code">writev</span>.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_enqv"><span class="bold_code">int driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_enqv"></a>
<p>This function enqueues the data in <span class="code">ev</span>, skipping the
first <span class="code">skip</span> bytes of it, at the end of the driver
queue. It is faster than <span class="code">driver_enq</span>, because the data
doesn't have to be copied.</p>
<p>The return value is 0.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_pushqv"><span class="bold_code">int driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pushqv"></a>
<p>This function puts the data in <span class="code">ev</span>, skipping the first
<span class="code">skip</span> bytes of it, at the head of the driver queue.
It is faster than <span class="code">driver_pushq</span>, because the data
doesn't have to be copied.</p>
<p>The return value is 0.</p>
<p>This function can be called from an arbitrary thread if a
<span class="bold_code"><a href="#ErlDrvPDL">port data lock</a></span>
associated with the <span class="code">port</span> is locked by the calling
thread during the call.</p>
</p></div>
<p><a name="driver_pdl_create"><span class="bold_code">ErlDrvPDL driver_pdl_create(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_create"></a>
<p>This function creates a port data lock associated with
the <span class="code">port</span>. <strong>NOTE</strong>: Once a port data lock has
been created, it has to be locked during all operations
on the driver queue of the <span class="code">port</span>.</p>
<p>On success a newly created port data lock is returned. On
failure <span class="code">NULL</span> is returned. <span class="code">driver_pdl_create()</span> will
fail if <span class="code">port</span> is invalid or if a port data lock already has
been associated with the <span class="code">port</span>.</p>
</p></div>
<p><a name="driver_pdl_lock"><span class="bold_code">void driver_pdl_lock(ErlDrvPDL pdl)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_lock"></a>
<p>This function locks the port data lock passed as argument
(<span class="code">pdl</span>).</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_pdl_unlock"><span class="bold_code">void driver_pdl_unlock(ErlDrvPDL pdl)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_unlock"></a>
<p>This function unlocks the port data lock passed as argument
(<span class="code">pdl</span>).</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_pdl_get_refc"><span class="bold_code">long driver_pdl_get_refc(ErlDrvPDL pdl)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_get_refc"></a>
<p>This function returns the current reference count of
the port data lock passed as argument (<span class="code">pdl</span>).</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_pdl_inc_refc"><span class="bold_code">long driver_pdl_inc_refc(ErlDrvPDL pdl)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_inc_refc"></a>
<p>This function increments the reference count of
the port data lock passed as argument (<span class="code">pdl</span>).</p>
<p>The current reference count after the increment has
been performed is returned.</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_pdl_dec_refc"><span class="bold_code">long driver_pdl_dec_refc(ErlDrvPDL pdl)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_pdl_dec_refc"></a>
<p>This function decrements the reference count of
the port data lock passed as argument (<span class="code">pdl</span>).</p>
<p>The current reference count after the decrement has
been performed is returned.</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="driver_monitor_process"><span class="bold_code">int driver_monitor_process(ErlDrvPort port, ErlDrvTermData process, ErlDrvMonitor *monitor)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_monitor_process"></a>
<p>Start monitoring a process from a driver. When a process is
monitored, a process exit will result in a call to the
provided <span class="bold_code"><a href="driver_entry.html#process_exit">process_exit</a></span> call-back
in the <span class="bold_code"><a href="driver_entry.html">ErlDrvEntry</a></span>
structure. The <span class="code">ErlDrvMonitor</span> structure is filled in, for later
removal or compare.</p>
<p>The <span class="code">process</span> parameter should be the return value of an
earlier call to <span class="bold_code"><a href="#driver_caller">driver_caller</a></span> or <span class="bold_code"><a href="#driver_connected">driver_connected</a></span> call.</p>
<p>The function returns 0 on success, < 0 if no call-back is
provided and > 0 if the process is no longer alive.</p>
</p></div>
<p><a name="driver_demonitor_process"><span class="bold_code">int driver_demonitor_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_demonitor_process"></a>
<p>This function cancels a monitor created earlier. </p>
<p>The function returns 0 if a monitor was removed and > 0
if the monitor did no longer exist.</p>
</p></div>
<p><a name="driver_get_monitored_process"><span class="bold_code">ErlDrvTermData driver_get_monitored_process(ErlDrvPort port, const ErlDrvMonitor *monitor)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_get_monitored_process"></a>
<p>The function returns the process id associated with a living
monitor. It can be used in the <span class="code">process_exit</span> call-back to
get the process identification for the exiting process.</p>
<p>The function returns <span class="code">driver_term_nil</span> if the monitor
no longer exists.</p>
</p></div>
<p><a name="driver_compare_monitors"><span class="bold_code">int driver_compare_monitors(const ErlDrvMonitor *monitor1, const ErlDrvMonitor *monitor2)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_compare_monitors"></a>
<p>This function is used to compare two <span class="code">ErlDrvMonitor</span>s. It
can also be used to imply some artificial order on monitors,
for whatever reason.</p>
<p>The function returns 0 if <span class="code">monitor1</span> and
<span class="code">monitor2</span> are equal, < 0 if <span class="code">monitor1</span> is less
than <span class="code">monitor2</span> and > 0 if <span class="code">monitor1</span> is greater
than <span class="code">monitor2</span>.</p>
</p></div>
<p><a name="add_driver_entry"><span class="bold_code">void add_driver_entry(ErlDrvEntry *de)</span></a><br></p>
<div class="REFBODY"><p>
<a name="add_driver_entry"></a>
<p>This function adds a driver entry to the list of drivers
known by Erlang. The <span class="bold_code"><a href="driver_entry.html#init">init</a></span> function of the <span class="code">de</span>
parameter is called.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>To use this function for adding drivers residing in
dynamically loaded code is dangerous. If the driver code
for the added driver resides in the same dynamically
loaded module (i.e. <span class="code">.so</span> file) as a normal
dynamically loaded driver (loaded with the <span class="code">erl_ddll</span>
interface), the caller should call <span class="bold_code"><a href="#driver_lock_driver">driver_lock_driver</a></span> before
adding driver entries.</p>
<p>Use of this function is generally deprecated.</p>
</p></div>
</div>
</p></div>
<p><a name="remove_driver_entry"><span class="bold_code">int remove_driver_entry(ErlDrvEntry *de)</span></a><br></p>
<div class="REFBODY"><p>
<a name="remove_driver_entry"></a>
<p>This function removes a driver entry <span class="code">de</span> previously
added with <span class="code">add_driver_entry</span>.</p>
<p>Driver entries added by the <span class="code">erl_ddll</span> erlang interface can
not be removed by using this interface.</p>
</p></div>
<p><a name="erl_errno_id"><span class="bold_code">char *erl_errno_id(int error)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_errno_id"></a>
<p>This function returns the atom name of the erlang error,
given the error number in <span class="code">error</span>. Error atoms are:
<span class="code">einval</span>, <span class="code">enoent</span>, etc. It can be used to make
error terms from the driver.</p>
</p></div>
<p><a name="set_busy_port"><span class="bold_code">void set_busy_port(ErlDrvPort port, int on)</span></a><br></p>
<div class="REFBODY"><p>
<a name="set_busy_port"></a>
<p>This function set and resets the busy status of the port. If
<span class="code">on</span> is 1, the port is set to busy, if it's 0 the port
is set to not busy.</p>
<p>When the port is busy, sending to it with <span class="code">Port ! Data</span>
or <span class="code">port_command/2</span>, will block the port owner process,
until the port is signaled as not busy.</p>
<p>If the
<span class="bold_code"><a href="driver_entry.html#driver_flags">ERL_DRV_FLAG_SOFT_BUSY</a></span>
has been set in the
<span class="bold_code"><a href="driver_entry.html">driver_entry</a></span>,
data can be forced into the driver via
<span class="bold_code"><a href="erlang.html#port_command-3">port_command(Port, Data, [force])</a></span>
even though the driver has signaled that it is busy.
</p>
</p></div>
<p><a name="set_port_control_flags"><span class="bold_code">void set_port_control_flags(ErlDrvPort port, int flags)</span></a><br></p>
<div class="REFBODY"><p>
<a name="set_port_control_flags"></a>
<p>This function sets flags for how the <span class="bold_code"><a href="driver_entry.html#control">control</a></span> driver entry
function will return data to the port owner process. (The
<span class="code">control</span> function is called from <span class="code">port_control/3</span>
in erlang.)</p>
<p>Currently there are only two meaningful values for
<span class="code">flags</span>: 0 means that data is returned in a list, and
<span class="code">PORT_CONTROL_FLAG_BINARY</span> means data is returned as
a binary from <span class="code">control</span>.</p>
</p></div>
<p><a name="driver_failure_eof"><span class="bold_code">int driver_failure_eof(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_failure_eof"></a>
<p>This function signals to erlang that the driver has
encountered an EOF and should be closed, unless the port was
opened with the <span class="code">eof</span> option, in that case eof is sent
to the port. Otherwise, the port is closed and an
<span class="code">'EXIT'</span> message is sent to the port owner process.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_failure_atom"><span class="bold_code">int driver_failure_atom(ErlDrvPort port, char *string)</span></a><br><a name="driver_failure_posix"><span class="bold_code">int driver_failure_posix(ErlDrvPort port, int error)</span></a><br><a name="driver_failure"><span class="bold_code">int driver_failure(ErlDrvPort port, int error)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_failure_atom"></a>
<a name="driver_failure_posix"></a>
<a name="driver_failure"></a>
<p>These functions signal to Erlang that the driver has
encountered an error and should be closed. The port is
closed and the tuple <span class="code">{'EXIT', error, Err}</span>, is sent to
the port owner process, where error is an error atom
(<span class="code">driver_failure_atom</span> and
<span class="code">driver_failure_posix</span>), or an integer
(<span class="code">driver_failure</span>).</p>
<p>The driver should fail only when in severe error situations,
when the driver cannot possibly keep open, for instance
buffer allocation gets out of memory. For normal errors
it is more appropriate to send error codes with
<span class="code">driver_output</span>.</p>
<p>The return value is 0.</p>
</p></div>
<p><a name="driver_connected"><span class="bold_code">ErlDrvTermData driver_connected(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_connected"></a>
<p>This function returns the port owner process.</p>
</p></div>
<p><a name="driver_caller"><span class="bold_code">ErlDrvTermData driver_caller(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_caller"></a>
<p>This function returns the process id of the process that
made the current call to the driver. The process id can be
used with <span class="code">driver_send_term</span> to send back data to the
caller. <span class="code">driver_caller()</span> only returns valid data
when currently executing in one of the following driver
callbacks:</p>
<dl>
<dt><strong><span class="bold_code"><a href="driver_entry.html#start">start</a></span></strong></dt>
<dd>Called from <span class="code">open_port/2</span>.</dd>
<dt><strong><span class="bold_code"><a href="driver_entry.html#output">output</a></span></strong></dt>
<dd>Called from <span class="code">erlang:send/2</span>, and
<span class="code">erlang:port_command/2</span>
</dd>
<dt><strong><span class="bold_code"><a href="driver_entry.html#outputv">outputv</a></span></strong></dt>
<dd>Called from <span class="code">erlang:send/2</span>, and
<span class="code">erlang:port_command/2</span>
</dd>
<dt><strong><span class="bold_code"><a href="driver_entry.html#control">control</a></span></strong></dt>
<dd>Called from <span class="code">erlang:port_control/3</span>
</dd>
<dt><strong><span class="bold_code"><a href="driver_entry.html#call">call</a></span></strong></dt>
<dd>Called from <span class="code">erlang:port_call/3</span>
</dd>
</dl>
</p></div>
<p><a name="driver_output_term"><span class="bold_code">int driver_output_term(ErlDrvPort port, ErlDrvTermData* term, int n)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_output_term"></a>
<p>This functions sends data in the special driver term
format. This is a fast way to deliver term data from a
driver. It also needs no binary conversion, so the port
owner process receives data as normal Erlang terms.</p>
<p>The <span class="code">term</span> parameter points to an array of
<span class="code">ErlDrvTermData</span>, with <span class="code">n</span> elements. This array
contains terms described in the driver term format. Every
term consists of one to four elements in the array. The
term first has a term type, and then arguments.</p>
<p>Tuple and lists (with the exception of strings, see below),
are built in reverse polish notation, so that to build a
tuple, the elements are given first, and then the tuple
term, with a count. Likewise for lists.</p>
<p>A tuple must be specified with the number of elements. (The
elements precede the <span class="code">ERL_DRV_TUPLE</span> term.)</p>
<p>A list must be specified with the number of elements,
including the tail, which is the last term preceding
<span class="code">ERL_DRV_LIST</span>.</p>
<p>The special term <span class="code">ERL_DRV_STRING_CONS</span> is used to
"splice" in a string in a list, a string given this way is
not a list per se, but the elements are elements of the
surrounding list.</p>
<div class="example"><pre>
Term type Argument(s)
===========================================
ERL_DRV_NIL
ERL_DRV_ATOM ErlDrvTermData atom (from driver_mk_atom(char *string))
ERL_DRV_INT ErlDrvSInt integer
ERL_DRV_UINT ErlDrvUInt integer
ERL_DRV_INT64 ErlDrvSInt64 *integer_ptr
ERL_DRV_UINT64 ErlDrvUInt64 *integer_ptr
ERL_DRV_PORT ErlDrvTermData port (from driver_mk_port(ErlDrvPort port))
ERL_DRV_BINARY ErlDrvBinary *bin, ErlDrvUInt len, ErlDrvUInt offset
ERL_DRV_BUF2BINARY char *buf, ErlDrvUInt len
ERL_DRV_STRING char *str, int len
ERL_DRV_TUPLE int sz
ERL_DRV_LIST int sz
ERL_DRV_PID ErlDrvTermData pid (from driver_connected(ErlDrvPort port) or driver_caller(ErlDrvPort port))
ERL_DRV_STRING_CONS char *str, int len
ERL_DRV_FLOAT double *dbl
ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len
</pre></div>
<p>The unsigned integer data type <span class="code">ErlDrvUInt</span> and the
signed integer data type <span class="code">ErlDrvSInt</span> are 64 bits wide
on a 64 bit runtime system and 32 bits wide on a 32 bit
runtime system. They were introduced in erts version 5.6,
and replaced some of the <span class="code">int</span> arguments in the list above.
</p>
<p>The unsigned integer data type <span class="code">ErlDrvUInt64</span> and the
signed integer data type <span class="code">ErlDrvSInt64</span> are always 64 bits
wide. They were introduced in erts version 5.7.4.
</p>
<p>To build the tuple <span class="code">{tcp, Port, [100 | Binary]}</span>, the
following call could be made.</p>
<div class="example"><pre>
ErlDrvBinary* bin = ...
ErlDrvPort port = ...
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("tcp"),
ERL_DRV_PORT, driver_mk_port(port),
ERL_DRV_INT, 100,
ERL_DRV_BINARY, bin, 50, 0,
ERL_DRV_LIST, 2,
ERL_DRV_TUPLE, 3,
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
</pre></div>
<p>Where <span class="code">bin</span> is a driver binary of length at least 50
and <span class="code">port</span> is a port handle. Note that the <span class="code">ERL_DRV_LIST</span>
comes after the elements of the list, likewise the
<span class="code">ERL_DRV_TUPLE</span>.</p>
<p>The term <span class="code">ERL_DRV_STRING_CONS</span> is a way to construct
strings. It works differently from how <span class="code">ERL_DRV_STRING</span>
works. <span class="code">ERL_DRV_STRING_CONS</span> builds a string list in
reverse order, (as opposed to how <span class="code">ERL_DRV_LIST</span>
works), concatenating the strings added to a list. The tail
must be given before <span class="code">ERL_DRV_STRING_CONS</span>.</p>
<p>The <span class="code">ERL_DRV_STRING</span> constructs a string, and ends
it. (So it's the same as <span class="code">ERL_DRV_NIL</span> followed by
<span class="code">ERL_DRV_STRING_CONS</span>.)</p>
<div class="example"><pre>
/* to send [x, "abc", y] to the port: */
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("x"),
ERL_DRV_STRING, (ErlDrvTermData)"abc", 3,
ERL_DRV_ATOM, driver_mk_atom("y"),
ERL_DRV_NIL,
ERL_DRV_LIST, 4
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
</pre></div>
<p></p>
<div class="example"><pre>
/* to send "abc123" to the port: */
ErlDrvTermData spec[] = {
ERL_DRV_NIL, /* with STRING_CONS, the tail comes first */
ERL_DRV_STRING_CONS, (ErlDrvTermData)"123", 3,
ERL_DRV_STRING_CONS, (ErlDrvTermData)"abc", 3,
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
</pre></div>
<p>The <span class="code">ERL_DRV_EXT2TERM</span> term type is used for passing a
term encoded with the
<span class="bold_code"><a href="erl_ext_dist.html">external format</a></span>,
i.e., a term that has been encoded by
<span class="bold_code"><a href="erlang.html#term_to_binary-2">erlang:term_to_binary</a></span>,
<span class="bold_code"><a href="javascript:erlhref('../../../doc/../','erl_interface','ei.html');">erl_interface</a></span>, etc.
For example, if <span class="code">binp</span> is a pointer to an <span class="code">ErlDrvBinary</span>
that contains the term <span class="code">{17, 4711}</span> encoded with the
<span class="bold_code"><a href="erl_ext_dist.html">external format</a></span>
and you want to wrap it in a two tuple with the tag <span class="code">my_tag</span>,
i.e., <span class="code">{my_tag, {17, 4711}}</span>, you can do as follows:
</p>
<div class="example"><pre>
ErlDrvTermData spec[] = {
ERL_DRV_ATOM, driver_mk_atom("my_tag"),
ERL_DRV_EXT2TERM, (ErlDrvTermData) binp->orig_bytes, binp->orig_size
ERL_DRV_TUPLE, 2,
};
driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
</pre></div>
<p>If you want to pass a binary and don't already have the content
of the binary in an <span class="code">ErlDrvBinary</span>, you can benefit from using
<span class="code">ERL_DRV_BUF2BINARY</span> instead of creating an <span class="code">ErlDrvBinary</span>
via <span class="code">driver_alloc_binary()</span> and then pass the binary via
<span class="code">ERL_DRV_BINARY</span>. The runtime system will often allocate
binaries smarter if <span class="code">ERL_DRV_BUF2BINARY</span> is used.
However, if the content of the binary to pass already resides in
an <span class="code">ErlDrvBinary</span>, it is normally better to pass the binary
using <span class="code">ERL_DRV_BINARY</span> and the <span class="code">ErlDrvBinary</span> in question.
</p>
<p>The <span class="code">ERL_DRV_UINT</span>, <span class="code">ERL_DRV_BUF2BINARY</span>, and
<span class="code">ERL_DRV_EXT2TERM</span> term types were introduced in the 5.6
version of erts.
</p>
<p>Note that this function is <strong>not</strong> thread-safe, not
even when the emulator with SMP support is used.</p>
</p></div>
<p><a name="driver_mk_atom"><span class="bold_code">ErlDrvTermData driver_mk_atom(char* string)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_mk_atom"></a>
<p>This function returns an atom given a name
<span class="code">string</span>. The atom is created and won't change, so the
return value may be saved and reused, which is faster than
looking up the atom several times.</p>
</p></div>
<p><a name="driver_mk_port"><span class="bold_code">ErlDrvTermData driver_mk_port(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_mk_port"></a>
<p>This function converts a port handle to the erlang term
format, usable in the <span class="code">driver_output_send</span> function.</p>
</p></div>
<p><a name="driver_send_term"><span class="bold_code">int driver_send_term(ErlDrvPort port, ErlDrvTermData receiver, ErlDrvTermData* term, int n)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_send_term"></a>
<p>This function is the only way for a driver to send data to
<strong>other</strong> processes than the port owner process. The
<span class="code">receiver</span> parameter specifies the process to receive
the data.</p>
<p>The parameters <span class="code">term</span> and <span class="code">n</span> do the same thing
as in <span class="bold_code"><a href="#driver_output_term">driver_output_term</a></span>.</p>
<p>This function is only thread-safe when the emulator with SMP
support is used.</p>
</p></div>
<p><a name="driver_async%20"><span class="bold_code">long driver_async (ErlDrvPort port, unsigned int* key, void (*async_invoke)(void*), void* async_data, void (*async_free)(void*))</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_async"></a>
<p>This function performs an asynchronous call. The function
<span class="code">async_invoke</span> is invoked in a thread separate from the
emulator thread. This enables the driver to perform
time-consuming, blocking operations without blocking the
emulator.</p>
<p>Erlang is by default started without an async thread pool. The
number of async threads that the runtime system should use
is specified by the
<span class="bold_code"><a href="erl.html#async_thread_pool_size">+A</a></span>
command line argument of <span class="bold_code"><a href="erl.html">erl(1)</a></span>.
If no async thread pool is available, the call is made
synchronously in the thread calling <span class="code">driver_async()</span>. The
current number of async threads in the async thread pool can be
retrieved via
<span class="bold_code"><a href="#driver_system_info">driver_system_info()</a></span>.</p>
<p>If there is a thread pool available, a thread will be
used. If the <span class="code">key</span> argument is null, the threads from the
pool are used in a round-robin way, each call to
<span class="code">driver_async</span> uses the next thread in the pool. With the
<span class="code">key</span> argument set, this behaviour is changed. The two
same values of <span class="code">*key</span> always get the same thread.</p>
<p>To make sure that a driver instance always uses the same
thread, the following call can be used:</p>
<p></p>
<div class="example"><pre>
unsigned int myKey = (unsigned int) myPort;
r = driver_async(myPort, &myKey, myData, myFunc);
</pre></div>
<p>It is enough to initialize <span class="code">myKey</span> once for each
driver instance.</p>
<p>If a thread is already working, the calls will be
queued up and executed in order. Using the same thread for
each driver instance ensures that the calls will be made in
sequence.</p>
<p>The <span class="code">async_data</span> is the argument to the functions
<span class="code">async_invoke</span> and <span class="code">async_free</span>. It's typically a
pointer to a structure that contains a pipe or event that
can be used to signal that the async operation completed.
The data should be freed in <span class="code">async_free</span>, because it's
called if <span class="code">driver_async_cancel</span> is called.</p>
<p>When the async operation is done, <span class="bold_code"><a href="driver_entry.html#ready_async">ready_async</a></span> driver
entry function is called. If <span class="code">async_ready</span> is null in
the driver entry, the <span class="code">async_free</span> function is called
instead.</p>
<p>The return value is a handle to the asynchronous task, which
can be used as argument to <span class="code">driver_async_cancel</span>.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>As of erts version 5.5.4.3 the default stack size for
threads in the async-thread pool is 16 kilowords,
i.e., 64 kilobyte on 32-bit architectures.
This small default size has been chosen since the
amount of async-threads might be quite large. The
default stack size is enough for drivers delivered
with Erlang/OTP, but might not be sufficiently large
for other dynamically linked in drivers that use the
driver_async() functionality. A suggested stack size
for threads in the async-thread pool can be configured
via the
<span class="bold_code"><a href="erl.html#async_thread_stack_size">+a</a></span>
command line argument of
<span class="bold_code"><a href="erl.html">erl(1)</a></span>.</p>
</p></div>
</div>
</p></div>
<p><a name="driver_async_cancel"><span class="bold_code">int driver_async_cancel(long id)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_async_cancel"></a>
<p>This function used to cancel a scheduled asynchronous operation,
if it was still in the queue. It returned 1 if it succeeded, and
0 if it failed.</p>
<p>Since it could not guarantee success, it was more or less useless.
The user had to implement synchronization of cancellation anyway.
It also unnecessarily complicated the implementation. Therefore,
as of OTP-R15B <span class="code">driver_async_cancel()</span> is deprecated, and
scheduled for removal in OTP-R16. It will currently always fail,
and return 0.</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p><span class="code">driver_async_cancel()</span> is deferred and will
be removed in the OTP-R16 release.</p>
</p></div>
</div>
</p></div>
<p><a name="driver_lock_driver"><span class="bold_code">int driver_lock_driver(ErlDrvPort port)</span></a><br></p>
<div class="REFBODY"><p>
<a name="driver_lock_driver"></a>
<p>This function locks the driver used by the port <span class="code">port</span>
in memory for the rest of the emulator process'
lifetime. After this call, the driver behaves as one of Erlang's
statically linked in drivers.</p>
</p></div>
<p><a name="driver_create_port"><span class="bold_code">ErlDrvPort driver_create_port(ErlDrvPort port, ErlDrvTermData owner_pid, char* name, ErlDrvData drv_data)</span></a><br></p>
<div class="REFBODY"><p>
<p>This function creates a new port executing the same driver
code as the port creating the new port.
A short description of the arguments:</p>
<dl>
<dt><strong><span class="code">port</span></strong></dt>
<dd>The port handle of the port (driver instance) creating
the new port.</dd>
<dt><strong><span class="code">owner_pid</span></strong></dt>
<dd>The process id of the Erlang process which will be
owner of the new port. This process will be linked
to the new port. You usually want to use
<span class="code">driver_caller(port)</span> as <span class="code">owner_pid</span>.</dd>
<dt><strong><span class="code">name</span></strong></dt>
<dd>The port name of the new port. You usually want to
use the same port name as the driver name
(<span class="bold_code"><a href="driver_entry.html#driver_name">driver_name</a></span>
field of the
<span class="bold_code"><a href="driver_entry.html">driver_entry</a></span>).</dd>
<dt><strong><span class="code">drv_data</span></strong></dt>
<dd>The driver defined handle that will be passed in subsequent
calls to driver call-backs. Note, that the
<span class="bold_code"><a href="driver_entry.html#start">driver start call-back</a></span>
will not be called for this new driver instance.
The driver defined handle is normally created in the
<span class="bold_code"><a href="driver_entry.html#start">driver start call-back</a></span>
when a port is created via
<span class="bold_code"><a href="erlang.html#open_port-2">erlang:open_port/2</a></span>. </dd>
</dl>
<p>The caller of <span class="code">driver_create_port()</span> is allowed to
manipulate the newly created port when <span class="code">driver_create_port()</span>
has returned. When
<span class="bold_code"><a href="#smp_support">port level locking</a></span>
is used, the creating port is, however, only allowed to
manipulate the newly created port until the current driver
call-back that was called by the emulator returns.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>When
<span class="bold_code"><a href="#smp_support">port level locking</a></span>
is used, the creating port is only allowed to manipulate
the newly created port until the current driver call-back
returns.</p>
</p></div>
</div>
</p></div>
<p><a name="erl_drv_thread_create"><span class="bold_code">int erl_drv_thread_create(char *name,
ErlDrvTid *tid,
void * (*func)(void *),
void *arg,
ErlDrvThreadOpts *opts)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created thread. It will be used
to identify the thread in planned future debug
functionality.
</dd>
<dt><strong><span class="code">tid</span></strong></dt>
<dd>A pointer to a thread identifier variable.</dd>
<dt><strong><span class="code">func</span></strong></dt>
<dd>A pointer to a function to execute in the created thread.</dd>
<dt><strong><span class="code">arg</span></strong></dt>
<dd>A pointer to argument to the <span class="code">func</span> function.</dd>
<dt><strong><span class="code">opts</span></strong></dt>
<dd>A pointer to thread options to use or <span class="code">NULL</span>.</dd>
</dl>
<p>This function creates a new thread. On success <span class="code">0</span> is returned;
otherwise, an <span class="code">errno</span> value is returned to indicate the error.
The newly created thread will begin executing in the function pointed
to by <span class="code">func</span>, and <span class="code">func</span> will be passed <span class="code">arg</span> as
argument. When <span class="code">erl_drv_thread_create()</span> returns the thread
identifier of the newly created thread will be available in
<span class="code">*tid</span>. <span class="code">opts</span> can be either a <span class="code">NULL</span> pointer, or a
pointer to an
<span class="bold_code"><a href="#ErlDrvThreadOpts">ErlDrvThreadOpts</a></span>
structure. If <span class="code">opts</span> is a <span class="code">NULL</span> pointer, default options
will be used; otherwise, the passed options will be used.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>You are not allowed to allocate the
<span class="bold_code"><a href="#ErlDrvThreadOpts">ErlDrvThreadOpts</a></span>
structure by yourself. It has to be allocated and
initialized by
<span class="bold_code"><a href="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</a></span>.
</p></p></div>
</div>
<p>The created thread will terminate either when <span class="code">func</span> returns
or if
<span class="bold_code"><a href="#erl_drv_thread_exit">erl_drv_thread_exit()</a></span>
is called by the thread. The exit value of the thread is either
returned from <span class="code">func</span> or passed as argument to
<span class="bold_code"><a href="#erl_drv_thread_exit">erl_drv_thread_exit()</a></span>.
The driver creating the thread has the responsibility of joining the
thread, via
<span class="bold_code"><a href="#erl_drv_thread_join">erl_drv_thread_join()</a></span>,
before the driver is unloaded. It is not possible to create
"detached" threads, i.e., threads that don't need to be joined.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>All created threads need to be joined by the driver before
it is unloaded. If the driver fails to join all threads
created before it is unloaded, the runtime system will
most likely crash when the code of the driver is unloaded.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_thread_opts_create"><span class="bold_code">ErlDrvThreadOpts *erl_drv_thread_opts_create(char *name)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_opts_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created thread options. It will be used
to identify the thread options in planned future debug
functionality.
</dd>
</dl>
<p>This function allocates and initialize a thread option
structure. On failure <span class="code">NULL</span> is returned. A thread option
structure is used for passing options to
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>.
If the structure isn't modified before it is passed to
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>,
the default values will be used.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>You are not allowed to allocate the
<span class="bold_code"><a href="#ErlDrvThreadOpts">ErlDrvThreadOpts</a></span>
structure by yourself. It has to be allocated and
initialized by <span class="code">erl_drv_thread_opts_create()</span>.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_thread_opts_destroy"><span class="bold_code">void erl_drv_thread_opts_destroy(ErlDrvThreadOpts *opts)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_opts_destroy"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">opts</span></strong></dt>
<dd>A pointer to thread options to destroy.</dd>
</dl>
<p>This function destroys thread options previously created by
<span class="bold_code"><a href="#erl_drv_thread_opts_create">erl_drv_thread_opts_create()</a></span>.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_thread_exit"><span class="bold_code">void erl_drv_thread_exit(void *exit_value)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_exit"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">exit_value</span></strong></dt>
<dd>A pointer to an exit value or <span class="code">NULL</span>.</dd>
</dl>
<p>This function terminates the calling thread with the exit
value passed as argument. You are only allowed to terminate
threads created with
<span class="bold_code"><a href="#erl_drv_thread_create">erl_drv_thread_create()</a></span>.
The exit value can later be retrieved by another thread via
<span class="bold_code"><a href="#erl_drv_thread_join">erl_drv_thread_join()</a></span>.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_thread_join"><span class="bold_code">int erl_drv_thread_join(ErlDrvTid tid, void **exit_value)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_join"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">tid</span></strong></dt>
<dd>The thread identifier of the thread to join.</dd>
<dt><strong><span class="code">exit_value</span></strong></dt>
<dd>A pointer to a pointer to an exit value, or <span class="code">NULL</span>.</dd>
</dl>
<p>This function joins the calling thread with another thread, i.e.,
the calling thread is blocked until the thread identified by
<span class="code">tid</span> has terminated. On success <span class="code">0</span> is returned;
otherwise, an <span class="code">errno</span> value is returned to indicate the error.
A thread can only be joined once. The behavior of joining
more than once is undefined, an emulator crash is likely. If
<span class="code">exit_value == NULL</span>, the exit value of the terminated thread
will be ignored; otherwise, the exit value of the terminated thread
will be stored at <span class="code">*exit_value</span>.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_thread_self"><span class="bold_code">ErlDrvTid erl_drv_thread_self(void)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_thread_self"></a>
<p>This function returns the thread identifier of the
calling thread.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_equal_tids"><span class="bold_code">int erl_drv_equal_tids(ErlDrvTid tid1, ErlDrvTid tid2)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_equal_tids"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">tid1</span></strong></dt>
<dd>A thread identifier.</dd>
<dt><strong><span class="code">tid2</span></strong></dt>
<dd>A thread identifier.</dd>
</dl>
<p>This function compares two thread identifiers for equality,
and returns <span class="code">0</span> it they aren't equal, and
a value not equal to <span class="code">0</span> if they are equal.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>A Thread identifier may be reused very quickly after
a thread has terminated. Therefore, if a thread
corresponding to one of the involved thread identifiers
has terminated since the thread identifier was saved,
the result of <span class="code">erl_drv_equal_tids()</span> might not give
the expected result.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_mutex_create"><span class="bold_code">ErlDrvMutex *erl_drv_mutex_create(char *name)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_mutex_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created mutex. It will be used
to identify the mutex in planned future debug functionality.
</dd>
</dl>
<p>This function creates a mutex and returns a pointer to it. On
failure <span class="code">NULL</span> is returned. The driver creating the mutex
has the responsibility of destroying it before the driver is
unloaded.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_mutex_destroy"><span class="bold_code">void erl_drv_mutex_destroy(ErlDrvMutex *mtx)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_mutex_destroy"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">mtx</span></strong></dt>
<dd>A pointer to a mutex to destroy.</dd>
</dl>
<p>This function destroys a mutex previously created by
<span class="bold_code"><a href="#erl_drv_mutex_create">erl_drv_mutex_create()</a></span>.
The mutex has to be in an unlocked state before being
destroyed.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_mutex_lock"><span class="bold_code">void erl_drv_mutex_lock(ErlDrvMutex *mtx)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_mutex_lock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">mtx</span></strong></dt>
<dd>A pointer to a mutex to lock.</dd>
</dl>
<p>This function locks a mutex. The calling thread will be
blocked until the mutex has been locked. A thread
which currently has locked the mutex may <strong>not</strong> lock
the same mutex again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave a mutex locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_mutex_trylock"><span class="bold_code">int erl_drv_mutex_trylock(ErlDrvMutex *mtx)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_mutex_trylock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">mtx</span></strong></dt>
<dd>A pointer to a mutex to try to lock.</dd>
</dl>
<p>This function tries to lock a mutex. If successful <span class="code">0</span>,
is returned; otherwise, <span class="code">EBUSY</span> is returned. A thread
which currently has locked the mutex may <strong>not</strong> try to
lock the same mutex again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave a mutex locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_mutex_unlock"><span class="bold_code">void erl_drv_mutex_unlock(ErlDrvMutex *mtx)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_mutex_unlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">mtx</span></strong></dt>
<dd>A pointer to a mutex to unlock.</dd>
</dl>
<p>This function unlocks a mutex. The mutex currently has to be
locked by the calling thread.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_cond_create"><span class="bold_code">ErlDrvCond *erl_drv_cond_create(char *name)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_cond_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created condition variable. It
will be used to identify the condition variable in planned
future debug functionality.
</dd>
</dl>
<p>This function creates a condition variable and returns a
pointer to it. On failure <span class="code">NULL</span> is returned. The driver
creating the condition variable has the responsibility of
destroying it before the driver is unloaded.</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_cond_destroy"><span class="bold_code">void erl_drv_cond_destroy(ErlDrvCond *cnd)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_cond_destroy"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">cnd</span></strong></dt>
<dd>A pointer to a condition variable to destroy.</dd>
</dl>
<p>This function destroys a condition variable previously
created by
<span class="bold_code"><a href="#erl_drv_cond_create">erl_drv_cond_create()</a></span>.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_cond_signal"><span class="bold_code">void erl_drv_cond_signal(ErlDrvCond *cnd)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_cond_signal"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">cnd</span></strong></dt>
<dd>A pointer to a condition variable to signal on.</dd>
</dl>
<p>This function signals on a condition variable. That is, if
other threads are waiting on the condition variable being
signaled, <strong>one</strong> of them will be woken.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_cond_broadcast"><span class="bold_code">void erl_drv_cond_broadcast(ErlDrvCond *cnd)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_cond_broadcast"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">cnd</span></strong></dt>
<dd>A pointer to a condition variable to broadcast on.</dd>
</dl>
<p>This function broadcasts on a condition variable. That is, if
other threads are waiting on the condition variable being
broadcasted on, <strong>all</strong> of them will be woken.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_cond_wait"><span class="bold_code">void erl_drv_cond_wait(ErlDrvCond *cnd, ErlDrvMutex *mtx)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_cond_wait"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">cnd</span></strong></dt>
<dd>A pointer to a condition variable to wait on.</dd>
<dt><strong><span class="code">mtx</span></strong></dt>
<dd>A pointer to a mutex to unlock while waiting.</dd>
<dt><strong><span class="code"></span></strong></dt>
<dd></dd>
</dl>
<p>This function waits on a condition variable. The calling
thread is blocked until another thread wakes it by signaling
or broadcasting on the condition variable. Before the calling
thread is blocked it unlocks the mutex passed as argument, and
when the calling thread is woken it locks the same mutex before
returning. That is, the mutex currently has to be locked by
the calling thread when calling this function.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p><span class="code">erl_drv_cond_wait()</span> might return even though
no-one has signaled or broadcasted on the condition
variable. Code calling <span class="code">erl_drv_cond_wait()</span> should
always be prepared for <span class="code">erl_drv_cond_wait()</span>
returning even though the condition that the thread was
waiting for hasn't occurred. That is, when returning from
<span class="code">erl_drv_cond_wait()</span> always check if the condition
has occurred, and if not call <span class="code">erl_drv_cond_wait()</span>
again.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_create"><span class="bold_code">ErlDrvRWLock *erl_drv_rwlock_create(char *name)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created rwlock. It will be used to
identify the rwlock in planned future debug functionality.
</dd>
</dl>
<p>This function creates an rwlock and returns a pointer to it. On
failure <span class="code">NULL</span> is returned. The driver creating the rwlock
has the responsibility of destroying it before the driver is
unloaded.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_destroy"><span class="bold_code">void erl_drv_rwlock_destroy(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_destroy"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to destroy.</dd>
</dl>
<p>This function destroys an rwlock previously created by
<span class="bold_code"><a href="#erl_drv_rwlock_create">erl_drv_rwlock_create()</a></span>.
The rwlock has to be in an unlocked state before being destroyed.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_rlock"><span class="bold_code">void erl_drv_rwlock_rlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_rlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to read lock.</dd>
</dl>
<p>This function read locks an rwlock. The calling thread will be
blocked until the rwlock has been read locked. A thread
which currently has read or read/write locked the rwlock may
<strong>not</strong> lock the same rwlock again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_tryrlock"><span class="bold_code">int erl_drv_rwlock_tryrlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_tryrlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to try to read lock.</dd>
</dl>
<p>This function tries to read lock an rwlock. If successful
<span class="code">0</span>, is returned; otherwise, <span class="code">EBUSY</span> is returned.
A thread which currently has read or read/write locked the
rwlock may <strong>not</strong> try to lock the same rwlock again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_runlock"><span class="bold_code">void erl_drv_rwlock_runlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_runlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to read unlock.</dd>
</dl>
<p>This function read unlocks an rwlock. The rwlock currently
has to be read locked by the calling thread.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_rwlock"><span class="bold_code">void erl_drv_rwlock_rwlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_rwlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to read/write lock.</dd>
</dl>
<p>This function read/write locks an rwlock. The calling thread
will be blocked until the rwlock has been read/write locked.
A thread which currently has read or read/write locked the
rwlock may <strong>not</strong> lock the same rwlock again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_tryrwlock"><span class="bold_code">int erl_drv_rwlock_tryrwlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_tryrwlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to try to read/write lock.</dd>
</dl>
<p>This function tries to read/write lock an rwlock. If successful
<span class="code">0</span>, is returned; otherwise, <span class="code">EBUSY</span> is returned.
A thread which currently has read or read/write locked the
rwlock may <strong>not</strong> try to lock the same rwlock again.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you leave an rwlock locked in an emulator thread
when you let the thread out of your control, you will
<strong>very likely</strong> deadlock the whole emulator.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_rwlock_rwunlock"><span class="bold_code">void erl_drv_rwlock_rwunlock(ErlDrvRWLock *rwlck)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_rwlock_rwunlock"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">rwlck</span></strong></dt>
<dd>A pointer to an rwlock to read/write unlock.</dd>
</dl>
<p>This function read/write unlocks an rwlock. The rwlock
currently has to be read/write locked by the calling thread.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_tsd_key_create"><span class="bold_code">int erl_drv_tsd_key_create(char *name, ErlDrvTSDKey *key)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_tsd_key_create"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">name</span></strong></dt>
<dd>A string identifying the created key. It will be used
to identify the key in planned future debug
functionality.
</dd>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A pointer to a thread specific data key variable.</dd>
</dl>
<p>This function creates a thread specific data key. On success
<span class="code">0</span> is returned; otherwise, an <span class="code">errno</span> value is returned
to indicate the error. The driver creating the key has the
responsibility of destroying it before the driver is unloaded.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_tsd_key_destroy"><span class="bold_code">void erl_drv_tsd_key_destroy(ErlDrvTSDKey key)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_tsd_key_destroy"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A thread specific data key to destroy.</dd>
</dl>
<p>This function destroys a thread specific data key
previously created by
<span class="bold_code"><a href="#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</a></span>.
All thread specific data using this key in all threads
have to be cleared (see
<span class="bold_code"><a href="#erl_drv_tsd_set">erl_drv_tsd_set()</a></span>)
prior to the call to <span class="code">erl_drv_tsd_key_destroy()</span>.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>A destroyed key is very likely to be reused soon.
Therefore, if you fail to clear the thread specific
data using this key in a thread prior to destroying
the key, you will <strong>very likely</strong> get unexpected
errors in other parts of the system.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_tsd_set"><span class="bold_code">void erl_drv_tsd_set(ErlDrvTSDKey key, void *data)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_tsd_set"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A thread specific data key.</dd>
<dt><strong><span class="code">data</span></strong></dt>
<dd>A pointer to data to associate with <span class="code">key</span>
in calling thread.
</dd>
</dl>
<p>This function sets thread specific data associated with
<span class="code">key</span> for the calling thread. You are only allowed to set
thread specific data for threads while they are fully under your
control. For example, if you set thread specific data in a thread
calling a driver call-back function, it has to be cleared, i.e.
set to <span class="code">NULL</span>, before returning from the driver call-back
function.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>If you fail to clear thread specific data in an
emulator thread before letting it out of your control,
you might not ever be able to clear this data with
later unexpected errors in other parts of the system as
a result.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_tsd_get"><span class="bold_code">void *erl_drv_tsd_get(ErlDrvTSDKey key)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_tsd_get"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A thread specific data key.</dd>
</dl>
<p>This function returns the thread specific data
associated with <span class="code">key</span> for the calling thread.
If no data has been associated with <span class="code">key</span> for
the calling thread, <span class="code">NULL</span> is returned.
</p>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_putenv"><span class="bold_code">int erl_drv_putenv(char *key, char *value)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_putenv"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A null terminated string containing the
name of the environment variable.</dd>
<dt><strong><span class="code">value</span></strong></dt>
<dd>A null terminated string containing the
new value of the environment variable.</dd>
</dl>
<p>This function sets the value of an environment variable.
It returns <span class="code">0</span> on success, and a value <span class="code">!= 0</span> on
failure.
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p><p>The result of passing the empty string ("") as a value
is platform dependent. On some platforms the value of the
variable is set to the empty string, on others, the
environment variable is removed.</p>
</p></div>
</div>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>Do <strong>not</strong> use libc's <span class="code">putenv</span> or similar
C library interfaces from a driver.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<p><a name="erl_drv_getenv"><span class="bold_code">int erl_drv_getenv(char *key, char *value, size_t *value_size)</span></a><br></p>
<div class="REFBODY"><p>
<a name="erl_drv_getenv"></a>
<p>Arguments:</p>
<dl>
<dt><strong><span class="code">key</span></strong></dt>
<dd>A null terminated string containing the
name of the environment variable.</dd>
<dt><strong><span class="code">value</span></strong></dt>
<dd>A pointer to an output buffer.</dd>
<dt><strong><span class="code">value_size</span></strong></dt>
<dd>A pointer to an integer. The integer is both used for
passing input and output sizes (see below).
</dd>
</dl>
<p>This function retrieves the value of an environment variable.
When called, <span class="code">*value_size</span> should contain the size of
the <span class="code">value</span> buffer. On success <span class="code">0</span> is returned,
the value of the environment variable has been written to
the <span class="code">value</span> buffer, and <span class="code">*value_size</span> contains the
string length (excluding the terminating null character) of
the value written to the <span class="code">value</span> buffer. On failure,
i.e., no such environment variable was found, a value less than
<span class="code">0</span> is returned. When the size of the <span class="code">value</span>
buffer is too small, a value greater than <span class="code">0</span> is returned
and <span class="code">*value_size</span> has been set to the buffer size needed.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p><p>Do <strong>not</strong> use libc's <span class="code">getenv</span> or similar
C library interfaces from a driver.
</p></p></div>
</div>
<p>This function is thread-safe.</p>
</p></div>
<h3><a name="id168586">SEE ALSO</a></h3>
<div class="REFBODY">
<p><span class="bold_code"><a href="driver_entry.html">driver_entry(3)</a></span>,
<span class="bold_code"><a href="javascript:erlhref('../../../doc/../','kernel','erl_ddll.html');">erl_ddll(3)</a></span>,
<span class="bold_code"><a href="erlang.html">erlang(3)</a></span></p>
<p>An Alternative Distribution Driver (ERTS User's
Guide Ch. 3)</p>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
167
