<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Falcon Feathers - The Standard Modules Reference. - All functions</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">All functions</h1>
<h3 class="faldoc_funcname"><a name="JSONdecode">JSONdecode()</a><span class="faldoc_belong"><a href="./module_feather_json.html">[in json]</a></p></h3>
<p class="item_brief">Decode an item stored in JSON format. </p>
<p class="faldoc_funcdecl">JSONdecode( source )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">A string or a stream from which to read the JSON data. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> a string containing the JSON string, if <b>stream</b> is nil </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JSONError.html">JSONError</a></td><td class="faldoc_raisedesc">if the input data cannot be parsed. </td></tr><tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">in case of error on the source stream. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="JSONencode">JSONencode()</a><span class="faldoc_belong"><a href="./module_feather_json.html">[in json]</a></p></h3>
<p class="item_brief">Encode an item in JSON format. </p>
<p class="faldoc_funcdecl">JSONencode( item, [stream], [uenc], [pretty], [readable] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">the item to be encoded in JSON format. </td></tr>
<tr><td class="faldoc_optparam">stream</td><td class="faldoc_optparamdesc">A stream on which to send the encoded result. </td></tr><tr><td class="faldoc_optparam">uenc</td><td class="faldoc_optparamdesc">Encode every character outside the ASCII printable range as \\uXXXX. </td></tr><tr><td class="faldoc_optparam">pretty</td><td class="faldoc_optparamdesc">Add spacing around separators and puntaction. </td></tr><tr><td class="faldoc_optparam">readable</td><td class="faldoc_optparamdesc">Put each item in lists on a separate line. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> a string containing the JSON string, if <b>stream</b> is nil </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JSONError.html">JSONError</a></td><td class="faldoc_raisedesc">if the passed item cannot be turned into a JSON representation. </td></tr><tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">in case of error on target stream. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="add">add()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Adds two items along the rules of VM '+' operator. </p>
<p class="faldoc_funcdecl">add( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The result of the sum. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function operates also on strings, arrays and dictionaries replicating the behavior of the "+" operator as it is performed by the VM. </p>
</p>
<h3 class="faldoc_funcname"><a name="at">at()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Passe-par-tout accessor function. </p>
<p class="faldoc_funcdecl">at( item, access, [value] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">An array, string, or any accessible item or collection. </td></tr><tr><td class="faldoc_param">access</td><td class="faldoc_paramdesc">A number, a range or a string to access the item. </td></tr>
<tr><td class="faldoc_optparam">value</td><td class="faldoc_optparamdesc">If given, will substitue the given item or range (new value). </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>AccessError</i></b></td><td class="faldoc_raisedesc">in case the accessor is invalid for the given item type. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function emulates all the language-level accessors provided by Falcon. Subscript accessors ([]) accepting numbers, ranges and generic items (for dictionaries) and property accessors (.) accepting strings are fully supported. When two parameters are passed, the function works in access semantics, while when the <b>value</b> parameter is also given, the function will work as an accessor/subscript assignment. In example, to change a string the <b>at</b> function can be used as a range accessor: </p>
<pre class="faldoc_code">
string = "hello"
string[0:1] = "H" //first letter up
at( string, [1:], "ELLO" ) // ...all up
> string
> "First letter: ", at( string, 0 )
// ^^^ same as string[0]
</pre>
<p class="faldoc_text">This function is also able to access and modify the bindings of arrays (i.e. like accessing the arrays using the "." operator), members of objects and instances and static methods of classes. Properties and bindings can be accessed by names as strings. In example: </p>
<pre class="faldoc_code">
// making a binding
// ... equivalent to "array.bind = ..."
array = []
at( array, "bind", "binding value" )
> array.bind
//... accessing a property
at( CurrentTime(), "toRFC2822" )()
</pre>
<p class="faldoc_text">Trying to access an item with an incompatible type of accessor (i.e. trying to access an object with a range, or a string with a string). </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> At the moment, the <b>at</b> function doesn't support BOM methods. </p>
</p>
<h3 class="faldoc_funcname"><a name="deq">deq()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a deep equality check. </p>
<p class="faldoc_funcdecl">deq( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the two items are deeply equal (same content). </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="div">div()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Divides two numeric operands along the rules of VM '/' operator. </p>
<p class="faldoc_funcdecl">div( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The result of the division. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="equal">equal()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being equal to the second. </p>
<p class="faldoc_funcdecl">equal( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a == b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="exec">exec()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Launches a process in place of the host process. </p>
<p class="faldoc_funcdecl">exec( command )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">command</td><td class="faldoc_paramdesc">A single string with the system command, or an array of parameters. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Never returns. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">if the process couldn't be created </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">On Unix-like systems, and wherever this feature is present, exec() calls an underlying OS request that swaps out the host process and executes the required command. This feature is often desirable for scripts that has just to setup an environment for a program they call thereafter, or for scripts selecting one program to execute from a list of possible programs. Where this function call is not provided, exec is implemented by calling the required process passing the current environment and then quitting the host program in the fastest possible way. </p>
<p class="faldoc_text">Embedders may be willing to turn off this feature by unexporting the exec symbol before linking the process module in the VM. </p>
<p class="faldoc_text"> The <b>command</b> parameter may be a complete string holding the command line of the program to be executed, or it may be an array where the first element is the program, and the other elements will be passed as parameters. If the program name is not an absolute path, it is searched in the system execution search path. </p>
</p>
<h3 class="faldoc_funcname"><a name="ge">ge()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being greater or equal to the second. </p>
<p class="faldoc_funcdecl">ge( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a >= b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getHostName">getHostName()</a><span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h3>
<p class="item_brief">Retreives the host name of the local machine. </p>
<p class="faldoc_funcdecl">getHostName</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the local machine name. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">if the host name can't be determined. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Returns the network name under which the machine is known to itself. By calling <a href="./functions.html#resolveAddress">resolveAddress</a> on this host name, it is possible to determine all the addressess of the interfaces that are available for networking. </p>
<p class="faldoc_text">If the system cannot provide an host name for the local machine, a NetError is raised. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> If the function fails, it is possible to retreive local addresses using through <a href="./functions.html#resolveAddress">resolveAddress</a> using the the name "localhost". </p>
</p>
<h3 class="faldoc_funcname"><a name="glog">glog()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log on the generic area. </p>
<p class="faldoc_funcdecl">glog( level, message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">level</td><td class="faldoc_paramdesc">The level of the log entry. </td></tr><tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
<p class="faldoc_text"> The <b>level</b> parameter can be an integer number, or one of the following conventional constants representing levels: </p>
<ul>
<li><b>LOGF</b>: failure; the application met a total failure condition and is going to halt. </li><li><b>LOGE</b>: error; the application met an error condition, possibly dangerous enough to cause future termination or malfunction, but not dangerous enough to justify immediate exit. </li><li><b>LOGW</b>: warning; the application met an unusual condition that that should be noted and known by other applications, developers or users checking for possible problems. </li><li><b>LOGI</b>: infromation; the application wants to indicate that a normal or expected event actually happened. </li><li><b>LOGD</b>: debug; A message useful to track debugging and development information. </li><li><b>LOGD1</b>: lower debug; debug used for very low level, and specialized debugging. </li><li><b>LOGD2</b>: still lower debug. </li>
</ul>
</p>
<h3 class="faldoc_funcname"><a name="glogd">glogd()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log a debug message on the generic area. </p>
<p class="faldoc_funcdecl">glogd( message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged at debug level. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area, indicating the debug level. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
</p>
<h3 class="faldoc_funcname"><a name="gloge">gloge()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log an error on the generic area. </p>
<p class="faldoc_funcdecl">gloge( message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged at error level. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area, indicating the error level. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
</p>
<h3 class="faldoc_funcname"><a name="glogf">glogf()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log a fatal error on the generic area. </p>
<p class="faldoc_funcdecl">glogf( message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged at fatal level. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area, indicating the fatal error level. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
</p>
<h3 class="faldoc_funcname"><a name="glogi">glogi()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log an information message on the generic area. </p>
<p class="faldoc_funcdecl">glogi( message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged at info level. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area, indicating the info level. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
</p>
<h3 class="faldoc_funcname"><a name="glogw">glogw()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Shortcut to log a warning on the generic area. </p>
<p class="faldoc_funcdecl">glogw( message, [code] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">message</td><td class="faldoc_paramdesc">The message to be logged at warn level. </td></tr>
<tr><td class="faldoc_optparam">code</td><td class="faldoc_optparamdesc">A numeric code representing an application specific message ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to call <b>log</b> on the <a href="./object_GeneralLog.html">GeneralLog</a> object, that is, on the default log area, indicating the warn level. </p>
<p class="faldoc_text">It is provided in this module for improved performance. </p>
</p>
<h3 class="faldoc_funcname"><a name="gminlog">gminlog()</a><span class="faldoc_belong"><a href="./module_feather_logging.html">[in Logging support]</a></p></h3>
<p class="item_brief">Determines what is the minimum log severity active on the GeneircLog area. </p>
<p class="faldoc_funcdecl">gminlog</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A number representing a log severity, or -1 </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function is actually a shortcut to <a href="./class_LogArea.html#minlog">LogArea.minlog</a> applied on <a href="./object_GeneralLog.html">GeneralLog</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="gt">gt()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being greater than the second. </p>
<p class="faldoc_funcdecl">gt( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a > b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="le">le()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being less or equal to the second. </p>
<p class="faldoc_funcdecl">le( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a <= b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="lt">lt()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being less than the second. </p>
<p class="faldoc_funcdecl">lt( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a < b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="mod">mod()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a modulo division on numeric operands along the rules of VM '%' operator. </p>
<p class="faldoc_funcdecl">mod( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The result of the modulo. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="mul">mul()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Multiplies two items along the rules of VM '*' operator. </p>
<p class="faldoc_funcdecl">mul( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The result of the multiplication. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function operates also on strings, arrays and dictionaries replicating the behavior of the "*" operator as it is performed by the VM. </p>
</p>
<h3 class="faldoc_funcname"><a name="neq">neq()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Performs a lexicographic check for the first operand being not equal to the second. </p>
<p class="faldoc_funcdecl">neq( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if a == b, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="pread">pread()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Executes an external process and waits for its termination. </p>
<p class="faldoc_funcdecl">pread( command, background )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">command</td><td class="faldoc_paramdesc">The command to be executed. </td></tr><tr><td class="faldoc_param">background</td><td class="faldoc_paramdesc">If given and true, the process runs hidden. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The full output generated by the rpcess. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">if the process couldn't be created. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function launches an external system command and waits until the command execution is terminated, returning the exit code of the child process. All the </p>
<p class="faldoc_text">for example: </p>
<pre class="faldoc_code">
dir_contents = pread( "ls" )
> dir_contents
</pre>
<p class="faldoc_text">If the process cannot be started if it fails to start, an error is raised. </p>
<p class="faldoc_text">\note This function uses the standard system shell to execute the passed commands, so it is possible to pipe applications and redirect streams via the standard "|" and ">" command line characters. </p>
</p>
<h3 class="faldoc_funcname"><a name="processId">processId()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Returns the process ID of the process hosting the Falcon VM. </p>
<p class="faldoc_funcdecl">processId</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">a numeric process ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">For command line Falcon interpreter, this ID may be considered the ID of the Falcon program being executed; in embedding applications, the function will return the process ID associated with the host application. </p>
</p>
<h3 class="faldoc_funcname"><a name="processKill">processKill()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Terminates the given process given its ID, if possible. </p>
<p class="faldoc_funcdecl">processKill( pid, [severe] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">pid</td><td class="faldoc_paramdesc">The Process ID of the process that should be terminated. </td></tr>
<tr><td class="faldoc_optparam">severe</td><td class="faldoc_optparamdesc">If given and true, use the maximum severity allowable to stop the given process. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True on success, false on failure. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The process having the given PID is terminated. On UNIX systems, a TERM signal is sent to the process. If severe is true, the process is stopped in the most hard way the system provides; i.e. in UNIX, KILL signal is sent. </p>
</p>
<h3 class="faldoc_funcname"><a name="resolveAddress">resolveAddress()</a><span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h3>
<p class="item_brief">Resolve a network address in a list of numeric IP fields. </p>
<p class="faldoc_funcdecl">resolveAddress( address )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">address</td><td class="faldoc_paramdesc">An host name, quad dot IP address or IPV6 address. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of IPv4 or IPv6 addresses. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">if the name resolution service is not available. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function tries to resolve an address or an host name into a list of addresses that can be used to connect directly via the protocols that are available on the machine. The way in which the function can resolve the addresses depends on the string that has been given, on the underlying system and on the name resolution services that the system can access. Also, the time by which a positive or negative result can be returned varies greatly between different systems. The caller must consider this function as potentially blocking the VM for a long time. </p>
<p class="faldoc_text">The other members of the Socket module do not need to be provided with already resolved addresses. In example, the connect method of the TCPSocket class can be provided with a host name or with an IP address; in the first case, the connect method will resolve the target address on its own. </p>
<p class="faldoc_text"> This function can be used on the value returned by <a href="./functions.html#getHostName">getHostName</a>, or using "localhost" as the <b>address</b> parameter, to receive a list of the interfaces that are available under the network name of the host the VM is running on. This is useful to i.e. bind some services only to one of the available interfaces. </p>
<p class="faldoc_text">The values in the returned array are the ones provided by the underlying name resolution system. They are not necessarily unique, and their order may change across different calls. </p>
<p class="faldoc_text"> If the function cannot find any host with the given name, an empty array is returned; if the name resolution service is not accessible, or if accessing it causes a system error, the function will raise a <a href="./class_NetError.html">NetError</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="socketErrorDesc">socketErrorDesc()</a><span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h3>
<p class="item_brief">Describe the meaning of a networking related system error code. </p>
<p class="faldoc_funcdecl">socketErrorDesc( code )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">code</td><td class="faldoc_paramdesc">The error code to be described. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string with a textual description of the error. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function invokes the system code-to-meaning translation for networking errors. The language in which the error code is described depends on the underlying system, </p>
<p class="faldoc_text"> The function can be applied to the fsError field of the <a href="./class_NetError.html">NetError</a> class to get a descriptive reason of why some operation failed, or on <a href="./class_Socket.html#lastError">Socket.lastError</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="sub">sub()</a><span class="faldoc_belong"><a href="./module_feather_funcext.html">[in funcext]</a></p></h3>
<p class="item_brief">Subtracts two items along the rules of VM '-' operator. </p>
<p class="faldoc_funcdecl">sub( a, b )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">a</td><td class="faldoc_paramdesc">First operand </td></tr><tr><td class="faldoc_param">b</td><td class="faldoc_paramdesc">Second operand </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The result of the subtraction. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function operates also on strings, arrays and dictionaries replicating the behavior of the "-" operator as it is performed by the VM. </p>
</p>
<h3 class="faldoc_funcname"><a name="system">system()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Executes an external process via command shell, and waits for its termination. </p>
<p class="faldoc_funcdecl">system( command, background )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">command</td><td class="faldoc_paramdesc">The command to be executed. </td></tr><tr><td class="faldoc_param">background</td><td class="faldoc_paramdesc">If given and true, the process runs hidden. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Exit status of the process. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">if the process couldn't be created. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function launches an external system command and waits until the command execution is complete, returning the exit code of the child process. The process is actually executed by passing the command string to the system command shell. In this way, it is possible to execute commands that are parsed by the shell. </p>
<p class="faldoc_text">This includes internal commands as "dir" in Windows systems, or small scripts as "for file in $(ls); do touch $file; done" if the system shell is sh. However, loading the shell may generate a needless overhead for the most common usages of system(). Use systemCall() if there isn't the need to have the system shell to parse the command. </p>
<p class="faldoc_text">If the background parameter is true, the execution of the child process is hidden; in example, on systems allocating virtual consoles to new processes, the child is given the parent's console instead. When running inside Window Managers and graphical systems, icons representing the process are usually not visible when this option is set. </p>
</p>
<h3 class="faldoc_funcname"><a name="systemCall">systemCall()</a><span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h3>
<p class="item_brief">Executes an external process and waits for its termination. </p>
<p class="faldoc_funcdecl">systemCall( command, background )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">command</td><td class="faldoc_paramdesc">The command to be executed. </td></tr><tr><td class="faldoc_param">background</td><td class="faldoc_paramdesc">If given and true, the process runs hidden. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Exit status of the process. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">if the process couldn't be created. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function launches an external system command and waits until the command execution is terminated, returning the exit code of the child process. The command is searched in the system path, if an absolute path is not given. A simple parsing is performed on the string executing the command, so that parameters between quotes are sent to the child process as a single parameter; in example: </p>
<pre class="faldoc_code">
retval = systemCall( "myprog alfa beta \"delta gamma\" omega" )
</pre>
<p class="faldoc_text">In this case, the child process will receive four parameters, the third of which being the two words between quotes. Those quotes are not passed to the child process. </p>
<p class="faldoc_text">If the background parameter is true, the execution of the child process is hidden; in example, on systems allocating virtual consoles to new processes, the child is given the parent's console instead. Icons representing the process are usually not visible when this option is set. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
