{"id":246,"date":"2015-02-22T11:53:04","date_gmt":"2015-02-22T11:53:04","guid":{"rendered":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=246"},"modified":"2017-05-12T14:16:56","modified_gmt":"2017-05-12T14:16:56","slug":"primitives","status":"publish","type":"page","link":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=246","title":{"rendered":"Primitives"},"content":{"rendered":"<p>Each primitive is given with its signature, consisting of a list of allowed typings, tried in order.\u00a0 A typing is of the form: <em>type<sub>1<\/sub><\/em>, &#8230;, <em>type<sub>n<\/sub><\/em> \u2192 <em>return-type<\/em><\/p>\n<ul>\n<li><em>n<\/em> may be 0, in which case we write just: \u2192 <em>return-type<\/em><\/li>\n<li>the symbol * used in place of <em>type<sub>i<\/sub><\/em> means that any type is admissible for argument\u00a0 <em>i<\/em>.<\/li>\n<\/ul>\n<h3>Arithmetic and logic<\/h3>\n<ul>\n<li><strong><code>random<\/code><\/strong> : \u2192 <code>int<\/code><br \/>\ndraw a pseudo-random number<\/li>\n<li><strong><code>bitdist<\/code><\/strong> : <em>type<\/em>, <em>type<\/em> \u2192 <code>int<\/code><br \/>\nwhere\u00a0<em>type<\/em> is any type from\u00a0 <code>int<\/code>, <code>uint<\/code>, <code>ipv4<\/code>, <code>ipv6<\/code>, <code>str<\/code>, <code>bstr<\/code>, <code>ctime<\/code>, <code>timeval<\/code>, <code>float<\/code>; note that the type of the two arguments must be the same<\/p>\n<ul>\n<li>returns: the number of bit positions at which the two arguments differ<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>bytedist<\/code><\/strong> : <em>type<\/em>, <em>type<\/em> \u2192 <code>int<\/code><br \/>\nwhere\u00a0<em>type<\/em> is any type from\u00a0 <code>int<\/code>, <code>uint<\/code>, <code>ipv4<\/code>, <code>ipv6<\/code>, <code>str<\/code>, <code>bstr<\/code>, <code>ctime<\/code>, <code>timeval<\/code>, <code>float<\/code>; note that the type of the two arguments must be the same<\/p>\n<ul>\n<li>returns: the number of byte positions at which the two arguments differ<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>defined<\/code><\/strong> : * \u2192 <code>int<\/code><br \/>\ntest whether the argument is null<\/p>\n<ul>\n<li>returns: 1 (true) if the argument is not null, 0 (false) if the argument is null<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3>Conversions<\/h3>\n<ul>\n<li><strong><code>sprintf<\/code><\/strong> : <code>str<\/code>, &#8230; \u2192 <code>str<\/code><br \/>\nconvert with format string (for formatting, see <code>printf<\/code>)<\/p>\n<ul>\n<li>e.g., <code>$cmd = sprintf (\"kill -9 %u, $pid)<\/code> with <code>$pid<\/code> containing 432 will compute the string <code>kill -9 432<\/code> and store it into <code>$cmd<\/code> (note that <code>sprintf<\/code> works differently from C)<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>str_from_int<\/code><\/strong> : <code>int<\/code> \u2192 <code>str<\/code><br \/>\nconvert number to printable representation, e.g., from -123 to <code>\"-123\"<\/code><\/li>\n<li><strong><code>int_from_str<\/code><\/strong> : <code>str<\/code> \u2192 <code>int<\/code><br \/>\nconvert string to number, e.g., from <code>\"-123\"<\/code> to -123<\/p>\n<ul>\n<li>ignores any suffix that does not make sense, hence will convert <code>\"-123ab45\"<\/code> to -123, for example<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>str_from_uint<\/code><\/strong> : <code>uint<\/code> \u2192 <code>str<\/code><br \/>\nconvert number to printable representation, e.g., from 123 to <code>\"123\"<\/code><\/li>\n<li><strong><code>str_from_uint_hex<\/code><\/strong> : <code>uint<\/code> \u2192 <code>str<\/code><br \/>\nconvert number to printable hexadecimal representation, e.g., from 123 to <code>\"7b\"<\/code><\/li>\n<li><strong><code>uint_from_str<\/code><\/strong> : <code>str<\/code> \u2192 <code>uint<\/code><br \/>\nconvert string to number, e.g., from <code>\"123\"<\/code> to 123<\/p>\n<ul>\n<li>ignores any suffix that does not make sense, hence will convert <code>\"123ab45\"<\/code> to 123, for example<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>str_from_float<\/code><\/strong> : <code>float<\/code> \u2192 <code>str<\/code><br \/>\nconvert number to printable representation, e.g., from -123.45 to <code>\"-123.45\"<\/code><\/li>\n<li><strong><code>float_from_str<\/code><\/strong> : <code>str<\/code> \u2192 <code>float<\/code><br \/>\nconvert string to number, e.g., from <code>\"-123.45E2\"<\/code> to -12345.0<\/p>\n<ul>\n<li>ignores any suffix that does not make sense, hence will convert <code>\"-123ab45\"<\/code> to -123.0, for example<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>str_from_regex<\/code><\/strong> : <code>regex<\/code> \u2192 <code>str<\/code><br \/>\nextract the string from the given regexp, e.g., <code>str_from_regex(_REGEX(\"a*ba*\"))<\/code> returns <code>\"a*ba*\"<\/code><\/li>\n<li><strong><code>regex_from_str<\/code><\/strong> : <code>str<\/code> \u2192 <code>regex<\/code><br \/>\ncompile the argument string to a regexp, that is, a regular expression matching machine<\/p>\n<ul>\n<li>may return the null object if argument string has invalid syntax<\/li>\n<li>equivalent to <a title=\"Expressions\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=283\"><code>_REGEX<\/code><\/a> construct, except the latter constructs a regexp at compile-time, and requires a string constant as argument; <code>regex_from_str<\/code> can be applied to any string computed at run-time<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>str_from_ctime<\/code><\/strong> :\u00a0<code>ctime<\/code> \u2192 <code>str<\/code><br \/>\nconvert time to printable representation<br \/>\nformat used is <code>\"%Y-%m-%dT%H:%M:%S%z\"<\/code> (IDMEF time format, with final time zone),<br \/>\nso output will be <code>\"2015-02-22T15:22:34+1\"<\/code> for February 22, 2015, 15 h. 22 min. 34 sec., UTC+1 time zone<\/li>\n<li><strong><code>ctime_from_str<\/code><\/strong> :\u00a0<code>str<\/code> \u2192 <code>ctime<\/code><br \/>\nconvert string to ctime, expects string to be in IDMEF or\u00a0<em>seconds<\/em><code>.<\/code><em>microseconds<\/em> format; in the second case, <em>microseconds<\/em> is ignored<\/li>\n<li><strong><code>str_from_timeval<\/code><\/strong> : <code>timeval<\/code> \u2192 <code>str<\/code><br \/>\nconvert time to printable representation<br \/>\nformat used is <em>seconds<\/em><code>.<\/code><em>microseconds<\/em><\/li>\n<li><strong><code>timeval_from_str<\/code><\/strong> :\u00a0<code>str<\/code> \u2192 <code>timeval<\/code><br \/>\nconvert string to timeval, expects string to be in IDMEF or\u00a0<em>seconds<\/em><code>.<\/code><em>microseconds<\/em> format<\/li>\n<li><strong><code>str_from_ipv4<\/code><\/strong> : <code>ipv4<\/code> \u2192 <code>str<\/code><br \/>\nconvert IPv4 address to printable representation, e.g., from 128.0.0.1 to <code>\"128.0.0.1\"<\/code><\/li>\n<li><strong><code>str_from_ipv6<\/code><\/strong> : <code>ipv6<\/code> \u2192 <code>str<\/code><br \/>\nconvert IPv6 address to printable representation, as 8 digits separated by <code>:<\/code><\/li>\n<li><strong><code>ipv4_from_ipv6<\/code><\/strong> : <code>ipv6<\/code> \u2192 <code>ipv4<\/code><br \/>\nconvert IPv6 address to IPv4 address, by truncating it to its last 4 bytes<\/li>\n<li><strong><code>ipv6_from_ipv4<\/code><\/strong> : <code>ipv4<\/code> \u2192 <code>ipv6<\/code><br \/>\nconvert IPv4 address to IPv6 address, by adding 12 zero bytes before the\u00a0 4 bytes of the IPv4 address<\/li>\n<li><strong><code>int_from_uint<\/code><\/strong> : <code>uint<\/code> \u2192 <code>int<\/code><br \/>\nconvert monotonously unsigned integer to integer, i.e. returns LONG_MAX if the unsigned integer is bigger than LONG_MAX<\/li>\n<li><strong><code>uint_from_int<\/code><\/strong> : <code>int<\/code> \u2192 <code>uint<\/code><br \/>\nconvert monotonously integer to unsigned integer, i.e. returns 0 if the integer is negative<\/li>\n<li><strong><code>int_from_float<\/code><\/strong> : <code>float<\/code> \u2192 <code>int<\/code><br \/>\nconvert monotonously float to integer, i.e. returns LONG_MAX if the float is bigger than LONG_MAX and LONG_MIN if the float is smaller than LONG_MIN<\/li>\n<li><strong><code>float_from_int<\/code><\/strong> : <code>int<\/code>\u00a0\u2192 <code>float<\/code><br \/>\nconvert integer to float<\/li>\n<li><strong><code>uint_from_float<\/code><\/strong> : <code>float<\/code> \u2192 <code>uint<\/code><br \/>\nconvert monotonously float to unsigned integer, i.e. returns ULONG_MAX if the float is bigger than ULONG_MAX and 0 if the float is negative<\/li>\n<li><strong><code>float_from_uint<\/code><\/strong> : <code>uint<\/code> \u2192 <code>float<\/code><br \/>\nconvert unsigned integer to float<\/li>\n<li><strong><code>add_slashes<\/code><\/strong> : <code>str<\/code> \u2192 <code>str<\/code><br \/>\nescape special characters: add a backslash <code>\\<\/code> in front of <code>'<\/code>, <code>\"<\/code>, and\u00a0<code>\\<\/code>, replace ASCII code 7 by <code>\\a<\/code> (two characters), 8 by <code>\\b<\/code>, 9 by <code>\\t<\/code>, 10 by <code>\\n<\/code>, 11 by <code>\\v<\/code>, 12 by <code>\\f<\/code>, 13 by <code>\\t<\/code>, all other characters with ASCII code &lt;32 or &gt;126 by a backslash followed by their octal value on three digits, and leave all other characters unchanged<\/li>\n<\/ul>\n<h3>Reaction and control<\/h3>\n<ul>\n<li><strong><code>report<\/code><\/strong>: \u2192 <code>int<\/code><br \/>\ngenerate report in standard report directories (by default, <code>\/usr\/local\/var\/orchids\/reports\/<\/code>).<br \/>\nThe report includes the values of the currently defined OrchIDS variables: if you want to report something, just have it stored into some variable.<br \/>\nDepending on which modules are installed, this will generate a report in a variety of formats.<\/p>\n<ul>\n<li>if\u00a0<code>mod_htmlstate<\/code>\u00a0is installed, then a report will be created in a file located in the standard report directory (by default, <code>\/usr\/local\/var\/orchids\/reports\/<\/code>);<br \/>\nthe file will be named\u00a0<code>report-<\/code><em>secs<\/em><code>-<\/code><em>msecs<\/em><code>.html<\/code>,\u00a0where\u00a0<em>secs<\/em>\u00a0and\u00a0<em>msecs<\/em>\u00a0are the current time, split into seconds and microseconds, as 8 hexadecimal digits;<br \/>\nthe file can be inspected from a remote\u00a0Web browser;<\/li>\n<li>if\u00a0<code>mod_iodef<\/code>\u00a0is installed, then a report will be created in a file located in the IODEF report directory (configurable through the IODEF module&#8217;s\u00a0<code>IODEFOutputDir<\/code>\u00a0directive);<br \/>\nthe file will be named\u00a0<code>report-<\/code><em>secs<\/em><code>-<\/code><em>msecs<\/em><code>.xml<\/code>,\u00a0where\u00a0<em>secs<\/em>\u00a0and\u00a0<em>msecs<\/em>\u00a0are the current time, split into seconds and microseconds, as 8 hexadecimal digits, and is obtained by instanciating\u00a0a template file;<\/li>\n<li>returns: <code>1<\/code> (true) in normal situations; <code>0<\/code> (false) if no active rule<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>system<\/code><\/strong> : <code>str<\/code> \u2192 <code>int<\/code><br \/>\nexecute a system command<\/p>\n<ul>\n<li>returns: the error code, 0 if everything went well<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>systemf<\/code><\/strong> : <code>str<\/code>, &#8230; \u2192 <code>int<\/code><br \/>\nexecute a system command with a format string (see <code>printf<\/code>), e.g., <code>systemf(\"kill -9 %u\", $pid);<\/code><\/p>\n<ul>\n<li>returns: the error code, 0 if everything went well<\/li>\n<li><code>systemf<\/code>(fmt, &#8230;) is equivalent to <code>system<\/code>(<code>sprintf<\/code>(fmt, &#8230;))<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3>Debugging<\/h3>\n<ul>\n<li><strong><code>print<\/code><\/strong> : * \u2192 <code>int<\/code><br \/>\nprint its argument on <code>stdout<\/code> (for debugging purposes)<\/p>\n<ul>\n<li>returns: <code>1<\/code> (true)<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>print_string<\/code><\/strong>\u00a0:\u00a0<code>str<\/code>\u00a0\u2192\u00a0<code>int<\/code><br \/>\nprint its argument, which must be a string, on\u00a0<code>stdout<br \/>\n<\/code>it prints it verbatim, without enclosing quotes and type info as <code>print<\/code>() does<\/p>\n<ul>\n<li>returns:\u00a0<code>1<\/code>\u00a0(true)<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>printf<\/code><\/strong> :\u00a0<code>str<\/code>, &#8230; \u2192 <code>int<\/code><br \/>\nprint its argument, which must be a string, with formatting, on\u00a0<code>stdout<br \/>\n<\/code>it prints it verbatim, without enclosing quotes, just like <code>print_string<\/code>() does<\/p>\n<ul>\n<li>e.g. <code>printf(\"pid=%u, source address=%i, sending 'ssh \\\"%S\\\"' command\", $pid, $source, $cmd)<\/code> will print <code>pid=433, source address=196.1.5.42, sending 'ssh \"cat \\\"collected data\\\"\"' command<\/code> if <code>pid<\/code>=433, <code>$source<\/code> holds the ipv4 address 196.1.5.42, and <code>$cmd<\/code> contains the string <code>cat \"collected data\"<\/code> (note the subtle use of <code>%S<\/code>, instead of <code>%s<\/code>: that adds the required backslashes around the double quotes from the latter string).<\/li>\n<li>returns:\u00a0<code>1<\/code>\u00a0(true)<\/li>\n<li>formatting is similar to C&#8217;s <code>printf<\/code>, but format specifiers are different:\n<ul>\n<li><code>%d<\/code>: print an <code>int<\/code> in decimal<\/li>\n<li><code>%u<\/code>: print an <code>uint<\/code> in decimal<\/li>\n<li><code>%x<\/code>: print an <code>uint<\/code> in hexadecimal<\/li>\n<li><code>%s<\/code>: print a <code>str<\/code> argument<\/li>\n<li><code>%S<\/code>: print an <code>str<\/code> argument, calling <code>addslashes<\/code> on it before<\/li>\n<li><code>%f<\/code>: print a <code>float<\/code><\/li>\n<li><code>%i<\/code>: print an <code>ipv4<\/code><\/li>\n<li><code>%I<\/code>: print an <code>ipv6<\/code><\/li>\n<li><code>%r<\/code>: print an <code>regex<\/code><\/li>\n<li><code>%t<\/code>: print an <code>ctime<\/code><\/li>\n<li><code>%T<\/code>: print an <code>timeval<\/code><\/li>\n<li><code>%%<\/code>: print a <code>%<\/code> sign<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<li><strong><code>shutdown<\/code><\/strong> : \u2192 <code>int<\/code><br \/>\nshut Orchids down<\/p>\n<ul>\n<li>does not return<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3>\u00a0Module-specific<\/h3>\n<ul>\n<li>The <a title=\"The consoles module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=322\"><code>consoles<\/code><\/a> module<\/li>\n<li>The <a title=\"The idmef module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=327\"><code>idmef<\/code><\/a> module<\/li>\n<li>The <a title=\"The iodef module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=331\"><code>iodef<\/code><\/a> module<\/li>\n<li>The <a title=\"The xml module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=362\"><code>xml<\/code><\/a> module<\/li>\n<li>The <a title=\"The metaevent module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=339\"><code>metaevent<\/code><\/a> module<\/li>\n<li>The <a title=\"The prelude module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=345\"><code>prelude<\/code><\/a> module<\/li>\n<li>The <a title=\"The sharedvars module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=353\"><code>sharedvars<\/code><\/a> module<\/li>\n<li>The <a title=\"The timeout module\" href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=357\"><code>timeout<\/code><\/a> module<\/li>\n<li><\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Each primitive is given with its signature, consisting of a list of allowed typings, tried in order.\u00a0 A typing is of the form: type1, &#8230;, typen \u2192 return-type n may be 0, in which case we write just: \u2192 return-type the symbol * used in place of typei means that any type is admissible for &hellip; <a href=\"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/?page_id=246\" class=\"more-link\">Continue reading <span class=\"screen-reader-text\">Primitives<\/span> <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"open","template":"","meta":{"footnotes":""},"class_list":["post-246","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/pages\/246","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=246"}],"version-history":[{"count":68,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/pages\/246\/revisions"}],"predecessor-version":[{"id":567,"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=\/wp\/v2\/pages\/246\/revisions\/567"}],"wp:attachment":[{"href":"https:\/\/projects.lsv.ens-paris-saclay.fr\/orchidsdoc\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=246"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}