Log of autodoc.git/traditional_manual/chapter

2020-06-10

2020-06-10 21:48:37 by Henrik Grubbström (Grubba) <grubba@grubba.org>

32f88f6e9411f5a4100351a160dff9b6e305513c (74410 lines) (+39463/-34947) ^{[

Show
| Annotate

]}
Branch: master

Stdio.Fd: Convert read() into a PIKEFUN.

13: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>compile()</code>, <code>cpp()</code>, <code>CompilerEnvironment.CPP</code> </dd></dl></dd></dl><dl><dt><h2 class='header'>Namespace predef::</h2> - </dt><dd> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This is the default namespace and contains lots of global symbols. + </dd></dl> <hr /> <dl class='group--doc'>
596: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + add_include_path + </dt> + <dd><code><code class='datatype'>void</code> add_include_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for include files. + This is the same as the command line option <tt>-I</tt>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note that the added directory will only be searched when using + < > to quote the included file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_include_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_module_path + </dt> + <dd><code><code class='datatype'>void</code> add_module_path(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>subpath</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for modules. + This is the same as the command line option <tt>-M</tt>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_module_path()</code> + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>path</code></dt> + <dd></dd><dd class='body--doc'>a string containing a path to search for Pike modules. May be a + directory, or a path to a ZIP archive. If a ZIP archive path is + provided, modules will be loaded from a directory, "modules" within + the ZIP archive (see the subpath argument). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>subpath</code></dt> + <dd></dd><dd class='body--doc'>if path is a ZIP archive, this argument will determine the path within + the archive to be searched. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_program_path + </dt> + <dd><code><code class='datatype'>void</code> add_program_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for programs. + This is the same as the command line option <tt>-P</tt>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_program_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method aggregate </dt> <dd><code><code class='datatype'>array</code> aggregate(<code class='datatype'>mixed</code> ... <code class='argument'>elements</code>)</code></dd>
1004: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + compile + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>program</code> compile(<code class='datatype'>string</code> <code class='argument'>source</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + compile_file + </dt> + <dd><code><code class='datatype'>program</code> compile_file(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>void</code>|<code class='datatype'>program</code> <code class='argument'>p</code>, <code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>o</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Compile the Pike code contained in the file <code>filename</code> into a program. + This function will compile the file <code>filename</code> to a Pike program that can + later be instantiated. It is the same as doing + <code class='expr'><code>compile_string</code>(<code>Stdio.read_file</code>(<code>filename</code>), <code>filename</code>)</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile()</code>, <code>compile_string()</code>, <code>cpp()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + compile_string + </dt> + <dd><code><code class='datatype'>program</code> compile_string(<code class='datatype'>string</code> <code class='argument'>source</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>void</code>|<code class='datatype'>program</code> <code class='argument'>p</code>, <code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>o</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>_show_if_constant_errors</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Compile the Pike code in the string <code>source</code> into a program. + If <code>filename</code> is not specified, it will default to <code class='expr'>"-"</code>. + Functionally equal to <code class='expr'><code>compile</code>(<code>cpp</code>(<code>source</code>, <code>filename</code>))</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile()</code>, <code>cpp()</code>, <code>compile_file()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method copy_value </dt> <dd><code><code class='datatype'>mixed</code> copy_value(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd>
1101: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + cpp + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>string</code> cpp(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>mapping</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_major</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_minor</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>picky_cpp</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method ctime </dt> <dd><code><code class='datatype'>string</code> ctime(<code class='datatype'>int</code> <code class='argument'>timestamp</code>)</code></dd>
1173: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + describe_backtrace + </dt> + <dd><code><code class='datatype'>string</code> describe_backtrace(<code class='datatype'>mixed</code> <code class='argument'>trace</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>linewidth</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return a readable message that describes where the backtrace + <code>trace</code> was made (by <code>backtrace</code>). + It may also be an error object or array (typically caught by a + <code>catch</code>), in which case the error message also is included in the + description. + Pass <code>linewidth</code> -1 to disable wrapping of the output. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>backtrace()</code>, <code>describe_error()</code>, <code>catch()</code>, <code>throw()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + describe_error + </dt> + <dd><code><code class='datatype'>string</code> describe_error(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the error message from an error object or array (typically + caught by a <code>catch</code>). The type of the error is checked, hence + <code>err</code> is declared as <code class='expr'>mixed</code> and not <code class='expr'>object|array</code>. + If an error message couldn't be obtained, a fallback message + describing the failure is returned. No errors due to incorrectness + in <code>err</code> are thrown. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>describe_backtrace()</code>, <code>get_backtrace</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method destruct </dt> <dd><code><code class='datatype'>bool</code> destruct(<code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>o</code>)</code></dd>
1321: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + error + </dt> + <dd><code><code class='datatype'>void</code> error(<code class='object unresolved'>sprintf_format</code> <code class='argument'>f</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Throws an error. A more readable version of the code + <code class='expr'>throw( ({ sprintf(f, @args), backtrace() }) )</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Constant is_gssapi_error Constant
1579: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + get_active_compilation_handler + </dt> + <dd><code><code class='object unresolved'>CompilationHandler</code> get_active_compilation_handler()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the currently active compilation compatibility handler, or + <tt>0</tt> (zero) if none is active. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function should only be used during a call of <code>compile()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_active_error_handler()</code>, <code>compile()</code>, + <code>master()->get_compilation_handler()</code>, <code>CompilationHandler</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_active_compiler </dt> <dd><code><code class='object unresolved'>CompilerEnvironment.PikeCompiler</code> get_active_compiler()</code></dd>
1599: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + get_active_error_handler + </dt> + <dd><code><code class='object unresolved'>CompilationHandler</code> get_active_error_handler()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the currently active compilation error handler + (second argument to <code>compile()</code>), or <tt>0</tt> (zero) if none + is active. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function should only be used during a call of <code>compile()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_active_compilation_handler()</code>, <code>compile()</code>, <code>CompilationHandler</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_all_groups </dt> <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>))) get_all_groups()</code></dd>
1646: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + get_backtrace + </dt> + <dd><code><code class='datatype'>array</code> get_backtrace(<code class='datatype'>object</code>|<code class='datatype'>array</code> <code class='argument'>err</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the backtrace array from an error object or array + (typically caught by a <code>catch</code>), or zero if there is none. Errors + are thrown on if there are problems retrieving the backtrace. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>describe_backtrace()</code>, <code>describe_error()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_groups_for_user </dt> <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_groups_for_user(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>user</code>)</code></dd>
1714: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + getenv + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) getenv(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>force_update</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Queries the environment variables. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>force_update</code></dt> + <dd></dd><dd class='body--doc'>A cached copy of the real environment is kept to make this + function quicker. If the optional flag <code>force_update</code> is nonzero + then the real environment is queried and the cache is updated from + it. That can be necessary if the environment changes through other + means than <code>putenv</code>, typically from a C-level library. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the whole environment as a mapping. Destructive + operations on the mapping will not affect the internal + environment representation. + Variable names and values cannot be wide strings nor contain + <code class='expr'>'\0'</code> characters. Variable names also cannot contain + <code class='expr'>'='</code> characters. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>On NT the environment variable name is case insensitive. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>putenv()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + getenv + </dt> + <dd><code><code class='datatype'>string</code> getenv(<code class='datatype'>string</code> <code class='argument'>varname</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>force_update</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Query the value of a specific environment variable. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>varname</code></dt> + <dd></dd><dd class='body--doc'>Environment variable to query. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>force_update</code></dt> + <dd></dd><dd class='body--doc'>A cached copy of the real environment is kept to make this + function quicker. If the optional flag <code>force_update</code> is nonzero + then the real environment is queried and the cache is updated from + it. That can be necessary if the environment changes through other + means than <code>putenv</code>, typically from a C-level library. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the value of the environment variable <code>varname</code> + if it exists, and <code class='expr'>0</code> (zero) otherwise. + Variable names and values cannot be wide strings nor contain + <code class='expr'>'\0'</code> characters. Variable names also cannot contain + <code class='expr'>'='</code> characters. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>On NT the environment variable name is case insensitive. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>putenv()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method getgrgid </dt> <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>)) getgrgid(<code class='datatype'>int</code> <code class='argument'>gid</code>)</code></dd>
2267: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + is_absolute_path + </dt> + <dd><code><code class='datatype'>int</code> is_absolute_path(<code class='datatype'>string</code> <code class='argument'>p</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Check if a path <code>p</code> is fully qualified (ie not relative). + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns 1 if the path is absolute, 0 otherwise. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Constant is_sql_null </dt>
2811: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + normalize_path + </dt> + <dd><code><code class='datatype'>string</code> normalize_path(<code class='datatype'>string</code> <code class='argument'>path</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Replaces "\" with "/" if runing on MS Windows. It is + adviced to use <code>System.normalize_path</code> instead. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method nth </dt> <dd><code><code class='datatype'>mixed</code> nth(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd>
2881: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + putenv + </dt> + <dd><code><code class='datatype'>void</code> putenv(<code class='datatype'>string</code> <code class='argument'>varname</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>value</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Sets the environment variable <code>varname</code> to <code>value</code>. + If <code>value</code> is omitted or zero, the environment variable + <code>varname</code> is removed. + <code>varname</code> and <code>value</code> cannot be wide strings nor contain + <code class='expr'>'\0'</code> characters. <code>varname</code> also cannot contain + <code class='expr'>'='</code> characters. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>On NT the environment variable name is case insensitive. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>getenv()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method query_num_arg </dt> <dd><code><code class='datatype'>int</code> query_num_arg()</code></dd>
2898: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + random + </dt> + <dd><code><code class='datatype'>array</code> random(<code class='datatype'>mapping</code> <code class='argument'>m</code>)</code> + <code><code class='datatype'>float</code> random(<code class='datatype'>float</code> <code class='argument'>max</code>)</code> + <code><code class='datatype'>int</code> random(<code class='datatype'>int</code> <code class='argument'>max</code>)</code> + <code><code class='datatype'>mixed</code> random(<code class='datatype'>object</code> <code class='argument'>o</code>)</code> + <code><code class='datatype'>mixed</code> random(<code class='datatype'>array</code>|<code class='datatype'>multiset</code> <code class='argument'>x</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get a random value generated by the default <code>RandomSystem</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>RandomSystem()->random()</code>, <code>random_string()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method random_seed </dt> <dd><code><code class='datatype'>void</code> random_seed(<code class='datatype'>int</code> <code class='argument'>seed</code>)</code></dd>
2916: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + random_string + </dt> + <dd><code><code class='datatype'>string</code> random_string(<code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get a string of random characters <code class='expr'>0..255</code> with the length <code>len</code> + from the default <code>RandomSystem</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>RandomSystem()->random_string()</code>, <code>random()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_include_path + </dt> + <dd><code><code class='datatype'>void</code> remove_include_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for include files. + This function performs the reverse operation of <code>add_include_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_include_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_module_path + </dt> + <dd><code><code class='datatype'>void</code> remove_module_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for modules. + This function performs the reverse operation of <code>add_module_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_module_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_program_path + </dt> + <dd><code><code class='datatype'>void</code> remove_program_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for programs. + This function performs the reverse operation of <code>add_program_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_program_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method removexattr </dt> <dd><code><code class='datatype'>void</code> removexattr(<code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code>)</code></dd>
4647: <dd class='body--doc'><code>__VERSION__</code>, <code>__MINOR__</code>, <code>__BUILD__</code>, <code>__REAL_VERSION__</code>, <code>__REAL_MINOR__</code>, <code>__REAL_BUILD__</code>, </dd></dl> - <dl><dt><h2 class='header'>Class Codec</h2> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + werror + </dt> + <dd><code><code class='datatype'>int</code> werror(<code class='datatype'>string</code> <code class='argument'>fmt</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Writes a string on stderr. Works just like <code>Stdio.File.write</code> + on <code>Stdio.stderr</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + write + </dt> + <dd><code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>fmt</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Writes a string on stdout. Works just like <code>Stdio.File.write</code> + on <code>Stdio.stdout</code>. + </dd></dl> + <dl><dt><h2 class='header'>Enum bool</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - + <dd class='body--doc'>Boolean datatype. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + false + Constant + true + </dt> + <dd><code><code class='datatype'>constant</code> <code class='constant'>false</code></code> + <code><code class='datatype'>constant</code> <code class='constant'>true</code></code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class Codec</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>An <code>Encoder</code> and a <code>Decoder</code> lumped into a single instance which can be used for both encoding and decoding. </dd></dl>
4895: </dd></dl><dl><dt><h2 class='header'>Class CompilerEnvironment</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The compiler environment. + <dd class='body--doc'><code>predef::CompilerEnvironment</code> that supports handlers. + The compiler environment. By inheriting this class and overloading the functions, it is possible to make a custom Pike compiler. </dd>
4912: <dt class='head--type'>Method compile </dt> + <dd><code><code class='datatype'>program</code> compile(<code class='datatype'>string</code> <code class='argument'>source</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + compile + </dt> <dd><code><code class='datatype'>program</code> compile(<code class='datatype'>string</code> <code class='argument'>source</code>, <code class='object unresolved'>CompilationHandler</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code>)</code></dd> <dt class='head--doc'>Description</dt>
4948: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + compile_exception + </dt> + <dd><code><code class='datatype'>int</code> compile_exception(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + format_exception + </dt> + <dd><code><code class='datatype'>string</code> format_exception(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_compilation_handler </dt> <dd><code><code class='datatype'>object</code> get_compilation_handler(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd>
5015: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + handle_import + </dt> + <dd><code><code class='datatype'>program</code> handle_import(<code class='datatype'>string</code> <code class='argument'>module</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compat_handler</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method handle_inherit </dt> <dd><code><code class='datatype'>program</code> handle_inherit(<code class='datatype'>string</code> <code class='argument'>inh</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>)</code></dd>
5031: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + handle_inherit + </dt> + <dd><code><code class='datatype'>program</code> handle_inherit(<code class='datatype'>string</code> <code class='argument'>inh</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compat_handler</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Inherit - + OrigCompilerEnvironment + </dt> + <dd><code>inherit predef::CompilerEnvironment : OrigCompilerEnvironment</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit Reporter </dt> <dd><code>inherit Reporter : Reporter</code></dd>
5050: resolv </dt> <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>identifier</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compat_handler</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv + </dt> + <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>identifier</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compat_handler</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Look up <code>identifier</code> in the current context. The default implementation calls the corresponding
5073: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + apply_handler + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>mixed</code> apply_handler(<code class='datatype'>string</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method change_cpp_compatibility </dt> <dd><code><code class='datatype'>void</code> change_cpp_compatibility(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> - + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + change_cpp_compatibility + </dt> + <dd><code><code class='datatype'>void</code> change_cpp_compatibility(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Change the pike compatibility level for this preprocessor to the specified version of Pike.
5116: <hr /> <dl class='group--doc'> + <dt class='head--type'>Variable + handler + Variable + compat_handler + </dt> + <dd><code><code class='datatype'>object</code> CompilerEnvironment.CPP.handler</code> + <code><code class='datatype'>object</code> CompilerEnvironment.CPP.compat_handler</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - + compile_exception + </dt> + <dd><code><code class='datatype'>int</code> compile_exception(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method cpp_error </dt> <dd><code><code class='datatype'>void</code> cpp_error(<code class='object unresolved'>sprintf_format</code> <code class='argument'>msg</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>arguments</code>)</code></dd>
5166: <tr><td><code><code class='key'>"prefix"</code> : <code class='datatype'>string</code></code></td><td>If a prefix is given, only prefixed directives will be processed. For example, if the prefix is <code class='expr'>"foo"</code>, then <code class='expr'>#foo_ifdef COND</code> and <code class='expr'>foo___LINE__</code> would be + processed, <code class='expr'>#ifdef COND</code> and <code class='expr'>__LINE__</code> + would not. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>current_file</code></dt> + <dd></dd><dd class='body--doc'>If the <code>current_file</code> argument has not been specified, + it will default to <code class='expr'>"-"</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>charset</code></dt> + <dd></dd><dd class='body--doc'>Turn on automatic character set detection if <code class='expr'>1</code>, otherwise + specifies the character set used by the input. + Defaults to <code class='expr'>"ISO-10646"</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>CompilerEnvironment.CPP CompilerEnvironment.CPP(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_major</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_minor</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>picky_cpp</code>)</code> + <code>CompilerEnvironment.CPP CompilerEnvironment.CPP(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>) <code class='argument'>options</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Initialize the preprocessor. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>options</code></dt> + <dd></dd><dd class='body--doc'>If the first argument is a mapping, no other arguments may follow. + Instead, they have to be given as members of the mapping (if wanted). + The following members are then recognized: + <table class='box'><tr><td><code><code class='key'>"current_file"</code> : <code class='datatype'>string</code></code></td><td>Name of the current file. It is used for generating + #line directives and for locating include files. + </td></tr> + <tr><td><code><code class='key'>"charset"</code> : <code class='datatype'>int</code>|<code class='datatype'>string</code></code></td><td>Charset to use when processing <code class='expr'>data</code>. + </td></tr> + <tr><td><code><code class='key'>"handler"</code> : <code class='datatype'>object</code></code></td><td>Compilation handler. + </td></tr> + <tr><td><code><code class='key'>"compat_major"</code> : <code class='datatype'>int</code></code></td><td>Sets the major pike version used for compat handling. + </td></tr> + <tr><td><code><code class='key'>"compat_minor"</code> : <code class='datatype'>int</code></code></td><td>Sets the minor pike version used for compat handling. + </td></tr> + <tr><td><code><code class='key'>"picky_cpp"</code> : <code class='datatype'>int</code></code></td><td>Generate more warnings. + </td></tr> + <tr><td><code><code class='key'>"keep_comments"</code> : <code class='datatype'>int</code></code></td><td>This option keeps <code>cpp()</code> from removing comments. + Useful in combination with the prefix feature below. + </td></tr> + <tr><td><code><code class='key'>"prefix"</code> : <code class='datatype'>string</code></code></td><td>If a prefix is given, only prefixed directives will be + processed. For example, if the prefix is <code class='expr'>"foo"</code>, then + <code class='expr'>#foo_ifdef COND</code> and <code class='expr'>foo___LINE__</code> would be processed, <code class='expr'>#ifdef COND</code> and <code class='expr'>__LINE__</code> would not. </td></tr> <tr><td><code><code class='key'>"predefines"</code> : <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)</code></td><td>Mapping of predefined macros in addition to those
5281: format_exception </dt> <dd><code><code class='datatype'>string</code> format_exception(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + format_exception + </dt> + <dd><code><code class='datatype'>string</code> format_exception(<code class='datatype'>mixed</code> <code class='argument'>err</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Format an exception caught by cpp as a suitable cpp error message.
5305: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + get_compilation_handler + </dt> + <dd><code><code class='datatype'>object</code> get_compilation_handler(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_predefines </dt> <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>object</code>) get_predefines()</code></dd> - + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_predefines + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>object</code>) get_predefines()</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Get the predefined macros for this preprocessor. This function is called by <code>init_pike_cpp()</code> to
5331: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + handle_include + </dt> + <dd><code><code class='datatype'>string</code> handle_include(<code class='datatype'>string</code> <code class='argument'>header_file</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>bool</code> <code class='argument'>is_local_ref</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + this_program + </dt> + <dd><code>inherit ::this_program : this_program</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method init_pike_cpp </dt> <dd><code><code class='datatype'>void</code> init_pike_cpp()</code></dd>
5350: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + read_include + </dt> + <dd><code><code class='datatype'>string</code> read_include(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method report </dt> - + <dd><code><code class='datatype'>void</code> report(<code class='object unresolved'>SeverityLevel</code> <code class='argument'>severity</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int(1..)</code> <code class='argument'>linenumber</code>, <code class='datatype'>string</code> <code class='argument'>subsystem</code>, <code class='object unresolved'>sprintf_format</code> <code class='argument'>message</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>extra_args</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Report a diagnostic from the preprocessor. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>severity</code></dt> + <dd></dd><dd class='body--doc'>The severity of the diagnostic. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>filename</code></dt> + <dd></dd> + <dt class='head--doc'>Parameter <code class='parameter'>linenumber</code></dt> + <dd></dd><dd class='body--doc'>Location which triggered the diagnostic. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>subsystem</code></dt> + <dd></dd><dd class='body--doc'>Typically <code class='expr'>"cpp"</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>message</code></dt> + <dd></dd><dd class='body--doc'>String with the diagnostic message, with optional + <code>sprintf()</code>-style formatting (if any <code>extra_args</code>). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>extra_args</code></dt> + <dd></dd><dd class='body--doc'>Extra arguments to <code>sprintf()</code>. + The default implementation does the following: + <ul> + <li>If there's a handler which implements <code>Reporter()->report()</code>, + call it with the same arguments. + </li><li>Otherwise if there's a handler which implements + <code>compile_warning()</code> or <code>compile_error()</code> that matches + <code>severity</code>, call it with suitable arguments. + </li><li>Otherwise if there's a compat handler, use it in the same + manner as the handler. + </li><li>Otherwise fall back to calling <code>::report()</code> with the + same arguments. + </li></ul> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In Pike 8.0 and earlier <code>MasterObject()->report()</code> was not called. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Reporter()->report()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + report + </dt> <dd><code><code class='datatype'>void</code> report(<code class='object unresolved'>SeverityLevel</code> <code class='argument'>severity</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int(1..)</code> <code class='argument'>linenumber</code>, <code class='datatype'>string</code> <code class='argument'>subsystem</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt>
5389: resolv </dt> <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>sym</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv + </dt> + <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>sym</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Attempt to resolve a symbol. The default implementation calls <code>CompilerEnvironment()->resolv()</code>
5450: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + apply_handler + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>mixed</code> apply_handler(<code class='datatype'>string</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method apply_type_attribute </dt> <dd><code><code class='datatype'>bool</code> apply_type_attribute(<code class='datatype'>string</code> <code class='argument'>attribute</code>, <code class='type'>type</code> <code class='argument'>a</code>, <code class='type'>type</code>|<code class='datatype'>void</code> <code class='argument'>b</code>)</code></dd>
5489: change_compiler_compatibility </dt> <dd><code><code class='datatype'>void</code> change_compiler_compatibility(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + change_compiler_compatibility + </dt> + <dd><code><code class='datatype'>void</code> change_compiler_compatibility(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Change compiler to attempt to be compatible with Pike <code>major</code>.<code>minor</code>. </dd></dl>
5497: <hr /> <dl class='group--doc'> + <dt class='head--type'>Variable + handler + Variable + compat_handler + </dt> + <dd><code><code class='datatype'>object</code> CompilerEnvironment.PikeCompiler.handler</code> + <code><code class='datatype'>object</code> CompilerEnvironment.PikeCompiler.compat_handler</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method compile </dt>
5570: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>CompilerEnvironment.PikeCompiler CompilerEnvironment.PikeCompiler(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>source</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Variable current_file </dt>
5599: get_compilation_handler </dt> <dd><code><code class='datatype'>object</code> get_compilation_handler(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_compilation_handler + </dt> + <dd><code><code class='datatype'>object</code> get_compilation_handler(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Get compatibility handler for Pike <code>major</code>.<code>minor</code>. </dd>
5614: get_default_module </dt> <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)|<code class='datatype'>object</code> get_default_module()</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_default_module + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)|<code class='datatype'>object</code> get_default_module()</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Get the default module for the current compatibility level (ie typically the value returned by <code>predef::all_constants()</code>).
5640: handle_import </dt> <dd><code><code class='datatype'>program</code> handle_import(<code class='datatype'>string</code> <code class='argument'>module</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + handle_import + </dt> + <dd><code><code class='datatype'>program</code> handle_import(<code class='datatype'>string</code> <code class='argument'>module</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Look up an import <code>module</code>. </dd></dl>
5652: handle_inherit </dt> <dd><code><code class='datatype'>program</code> handle_inherit(<code class='datatype'>string</code> <code class='argument'>inh</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + handle_inherit + </dt> + <dd><code><code class='datatype'>program</code> handle_inherit(<code class='datatype'>string</code> <code class='argument'>inh</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Look up an inherit <code>inh</code> in the current program. </dd></dl>
5685: <hr /> <dl class='group--doc'> + <dt class='head--type'>Inherit + this_program + </dt> + <dd><code>inherit ::this_program : this_program</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method pop_type_attribute </dt>
5739: report </dt> <dd><code><code class='datatype'>void</code> report(<code class='object unresolved'>SeverityLevel</code> <code class='argument'>severity</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int</code> <code class='argument'>linenumber</code>, <code class='datatype'>string</code> <code class='argument'>subsystem</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + report + </dt> + <dd><code><code class='datatype'>void</code> report(<code class='object unresolved'>SeverityLevel</code> <code class='argument'>severity</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int</code> <code class='argument'>linenumber</code>, <code class='datatype'>string</code> <code class='argument'>subsystem</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Report a diagnostic from the compiler. The default implementation attempts to call the first
5784: resolv </dt> <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>identifier</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv + </dt> + <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>identifier</code>)</code></dd> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>Resolve the symbol <code>identifier</code>. The default implementation calls <code>CompilerEnvironment()->resolv()</code>
6246: doesn't point to any item. </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class MasterObject</h2> - </dt><dd> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Master control program for Pike. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>predef::master()</code>, <code>predef::replace_master()</code> + </dd></dl> <hr /> <dl class='group--doc'>
6289: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + _main + </dt> + <dd><code><code class='datatype'>void</code> _main(<code class='datatype'>array</code>(<code class='datatype'>string(8bit)</code>) <code class='argument'>orig_argv</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when all the driver is done with all setup + of modules, efuns, tables etc. etc. and is ready to start executing + _real_ programs. It receives the arguments not meant for the driver. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _pike_file_name + Variable + _master_file_name + </dt> + <dd><code><code class='datatype'>string</code> MasterObject._pike_file_name</code> + <code><code class='datatype'>string</code> MasterObject._master_file_name</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>These are useful if you want to start other Pike processes + with the same options as this one was started with. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_filesystem_handler + </dt> + <dd><code><code class='datatype'>mixed</code> add_filesystem_handler(<code class='datatype'>string</code> <code class='argument'>mountpoint</code>, <code class='datatype'>object</code> <code class='argument'>filesystem</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>mount a filesystem handler to be used by the resolver. on its own does noting, + but may be used with <code>add_module_path</code> and friends to enable modules to be loaded + from Filesystem objects. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>mountpoint</code></dt> + <dd></dd><dd class='body--doc'>the location in the filesystem to mount the handler + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>filesystem</code></dt> + <dd></dd><dd class='body--doc'>a filesystem object that will handle requests for the given mountpoint. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>master()->add_filesystem_handler("/foo/bar.zip", Filesystem.Zip("/foo/bar.zip")); + master()->add_module_path("/foo/bar.zip/lib"); + </pre></dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>find_handler_for_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + asyncp + </dt> + <dd><code><code class='datatype'>bool</code> asyncp()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns 1 if we're in async-mode, e.g. if the main method has + returned a negative number. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + backend_thread + </dt> + <dd><code><code class='datatype'>object</code> backend_thread()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The backend_thread() function is useful to determine if you are + the backend thread - important when doing async/sync protocols. + This method is only available if thread_create is present. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + bt_max_string_len + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> MasterObject.<code class='constant'>bt_max_string_len</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This constant contains the maximum length of a function entry in a + backtrace. Defaults to 200 if no BT_MAX_STRING_LEN define has been + given. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method cast_to_object </dt> - + <dd><code><code class='datatype'>object</code> cast_to_object(<code class='datatype'>string</code> <code class='argument'>oname</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>current_handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when the drivers wants to cast a string + to an object because of an implict or explicit cast. This function + may also receive more arguments in the future. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + cast_to_object + </dt> <dd><code><code class='datatype'>object</code> cast_to_object(<code class='datatype'>string</code> <code class='argument'>str</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>)</code></dd> <dt class='head--doc'>Description</dt>
6315: <dt class='head--type'>Method cast_to_program </dt> + <dd><code><code class='datatype'>program</code> cast_to_program(<code class='datatype'>string</code> <code class='argument'>pname</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when the driver wants to cast a string + to a program, this might be because of an explicit cast, an inherit + or a implict cast. In the future it might receive more arguments, + to aid the master finding the right program. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + cast_to_program + </dt> <dd><code><code class='datatype'>program</code> cast_to_program(<code class='datatype'>string</code> <code class='argument'>str</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>)</code></dd> <dt class='head--doc'>Description</dt>
6336: <hr /> <dl class='group--doc'> + <dt class='head--type'>Variable + cflags + </dt> + <dd><code><code class='datatype'>string</code> MasterObject.cflags</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Flags suitable for use when compiling Pike C modules + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + compat_major + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.compat_major</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Major pike version to emulate. + This is typically set via the option <code class='expr'>"-V"</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compat_minor</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + compat_minor + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.compat_minor</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Minor pike version to emulate. + This is typically set via the option <code class='expr'>"-V"</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compat_major</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - + compile_error + </dt> + <dd><code><code class='datatype'>void</code> compile_error(<code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>int</code> <code class='argument'>line</code>, <code class='datatype'>string</code> <code class='argument'>err</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called whenever a compile error occurs. <code>line</code> + is zero for errors that aren't associated with any specific line. + <code>err</code> is not newline terminated. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile_warning()</code>, <code>compile_exception()</code>, + <code>get_inhibit_compile_errors()</code>, <code>set_inhibit_compile_errors()</code>, + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + compile_exception + </dt> + <dd><code><code class='datatype'>int</code> compile_exception(<code class='datatype'>array</code>|<code class='datatype'>object</code> <code class='argument'>trace</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when an exception is caught during + compilation. Its message is also reported to <code>compile_error</code> if + this function returns zero. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile_error()</code>, <code>compile_warning()</code>, + <code>get_inhibit_compile_errors()</code>, <code>set_inhibit_compile_errors()</code>, + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + compile_warning + </dt> + <dd><code><code class='datatype'>void</code> compile_warning(<code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>int</code> <code class='argument'>line</code>, <code class='datatype'>string</code> <code class='argument'>err</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called whenever a compile warning occurs. <code>line</code> + is zero for warnings that aren't associated with any specific + line. <code>err</code> is not newline terminated. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>compile_error()</code>, <code>compile_exception()</code>, + <code>get_inhibit_compile_errors()</code>, <code>set_inhibit_compile_errors()</code>, + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + currentversion + </dt> + <dd><code><code class='object unresolved'>Version</code> MasterObject.currentversion</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Version information about the current Pike version. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method decode_charset </dt> - + <dd><code><code class='datatype'>string</code> decode_charset(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code> <code class='argument'>charset</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called by cpp() when it wants to do + character code conversion. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + decode_charset + </dt> <dd><code><code class='datatype'>string</code> decode_charset(<code class='datatype'>string</code> <code class='argument'>raw</code>, <code class='datatype'>string</code> <code class='argument'>charset</code>)</code></dd> <dt class='head--doc'>Description</dt>
6396: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + describe_function + </dt> + <dd><code><code class='datatype'>string</code> describe_function(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Function called by <code>describe_backtrace()</code> to describe + functions in the backtrace. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + describe_module + </dt> + <dd><code><code class='datatype'>string</code> describe_module(<code class='datatype'>object</code>|<code class='datatype'>program</code> <code class='argument'>mod</code>, <code class='datatype'>array</code>(<code class='datatype'>object</code>)|<code class='datatype'>void</code> <code class='argument'>ret_obj</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Describe the path to the module <code>mod</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>mod</code></dt> + <dd></dd><dd class='body--doc'>If <code>mod</code> is a program, attempt to describe the path + to a clone of <code>mod</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>ret_obj</code></dt> + <dd></dd><dd class='body--doc'>If an instance of <code>mod</code> is found, it will be returned + by changing element <code class='expr'>0</code> of <code>ret_obj</code>. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The a description of the path. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The returned description will end with a proper indexing method + currently either <code class='expr'>"."</code> or <code class='expr'>"->"</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + describe_object + </dt> + <dd><code><code class='datatype'>string</code> describe_object(<code class='datatype'>object</code> <code class='argument'>o</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Function called by <code class='expr'>sprintf("%O")</code> for objects that don't + have an <code>lfun::_sprintf()</code>, or have one that returns <code class='expr'>UNDEFINED</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + describe_program + </dt> + <dd><code><code class='datatype'>string</code> describe_program(<code class='datatype'>program</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>p</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Function called by <code class='expr'>sprintf("%O")</code> for programs. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + doc_prefix + </dt> + <dd><code><code class='datatype'>string</code> MasterObject.doc_prefix</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Prefix for autodoc files. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + programs + Variable + documentation + Variable + source_cache + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>program</code>|<code class='object unresolved'>NoValue</code>) MasterObject.programs</code> + <code><code class='datatype'>mapping</code>(<code class='datatype'>program</code>:<code class='datatype'>object</code>) MasterObject.documentation</code> + <code><code class='datatype'>mapping</code>(<code class='datatype'>program</code>:<code class='datatype'>string</code>) MasterObject.source_cache</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Mapping containing the cache of currently compiled files. + This mapping currently has the following structure: + <table class='box'><tr><td><code><code class='key'>filename</code> : <code class='datatype'>program</code></code></td></tr> + </table>The filename path separator is / on both NT and UNIX. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Special cases: The current master program is available under the + name <code class='expr'>"/master"</code>, and the program containing the <code>main</code> + function under <code class='expr'>"/main"</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + enable_source_cache + </dt> + <dd><code><code class='datatype'>void</code> enable_source_cache()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Enable caching of sources from compile_string() + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + fc_reverse_lookup + </dt> + <dd><code><code class='datatype'>string</code> fc_reverse_lookup(<code class='datatype'>object</code> <code class='argument'>obj</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the path for <code>obj</code> in <code>fc</code>, if it got any. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + find_handler_for_path + </dt> + <dd><code><code class='datatype'>string</code> find_handler_for_path(<code class='datatype'>string</code> <code class='argument'>file</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the mountpoint for the filesystem handler handling the + <code>file</code> (if any). + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_filesystem_handler()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_compat_master + </dt> + <dd><code><code class='datatype'>object</code> get_compat_master(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return a master object compatible with the specified version of Pike. + This function is used to implement the various compatibility versions + of <code>master()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_compilation_handler()</code>, <code>master()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method get_compilation_handler </dt> <dd><code><code class='object unresolved'>CompilationHandler</code> get_compilation_handler(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd>
6419: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + get_inhibit_compile_errors + </dt> + <dd><code><code class='datatype'>mixed</code> get_inhibit_compile_errors()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get the current compile error, warning and exception behaviour. + See <code>set_inhibit_compile_errors()</code> for details. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_inhibit_compile_errors()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_precompiled_mtime + </dt> + <dd><code><code class='datatype'>int</code> get_precompiled_mtime(<code class='datatype'>string</code> <code class='argument'>id</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Given an identifier returned by query_precompiled_names, returns + the mtime of the precompiled entry. Returns -1 if there is no + entry. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + handle_attribute + </dt> + <dd><code><code class='modifier'>optional</code> <code class='datatype'>bool</code> handle_attribute(<code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='datatype'>string</code> <code class='argument'>attribute</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called in runtime check_types mode (<tt>-rt</tt>), + when encountering a soft cast to an attributed type. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>Value that is about to receive the attribute. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>attribute</code></dt> + <dd></dd><dd class='body--doc'>Type attribute to validate. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns one of: + <table class='box'><tr><td><code><code class='key'>1</code></code></td><td>If the attribute is valid for the value. + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>If the attribute is not valid for the value. + </td></tr> + <tr><td><code><code class='key'>UNDEFINED</code></code></td><td>If the attribute is unsupported. + </td></tr> + </table>The default master implements validation of the <code class='expr'>"utf8"</code> + attribute. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method handle_error </dt> <dd><code><code class='datatype'>void</code> handle_error(<code class='datatype'>mixed</code> <code class='argument'>exception</code>)</code></dd>
6436: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + handle_error + </dt> + <dd><code><code class='datatype'>void</code> handle_error(<code class='datatype'>array</code>|<code class='datatype'>object</code> <code class='argument'>trace</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when an error occurs that is not caught + with catch(). + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + handle_inherit + </dt> + <dd><code><code class='datatype'>program</code> handle_inherit(<code class='datatype'>string</code> <code class='argument'>pname</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called whenever a inherit is called for. + It is supposed to return the program to inherit. + The first argument is the argument given to inherit, and the second + is the file name of the program currently compiling. Note that the + file name can be changed with #line, or set by compile_string, so + it can not be 100% trusted to be a filename. + previous_object(), can be virtually anything in this function, as it + is called from the compiler. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + include_prefix + </dt> + <dd><code><code class='datatype'>string</code> MasterObject.include_prefix</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Prefix for Pike-related C header files. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Inherit - + Codec + </dt> + <dd><code>inherit Codec : Codec</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + CompatResolver + </dt> + <dd><code>inherit CompatResolver : CompatResolver</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit CompilationHandler </dt> <dd><code>inherit CompilationHandler : CompilationHandler</code></dd>
6449: <hr /> <dl class='group--doc'> + <dt class='head--type'>Inherit + Pike_8_0_master + </dt> + <dd><code><code class='modifier'>protected</code> inherit Pike_8_0_master : Pike_8_0_master</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Namespaces for compat masters. + This inherit is used to provide compatibility namespaces + for <code>get_compat_master()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_compat_master()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + is_pike_master + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.is_pike_master</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This integer variable should exist in any object that aspires to be + the master. It gets set to 1 when the master is installed, and is + therefore set in any object that is or has been the master. That + makes the Encoder class encode references to the master and all + ex-masters as references to the current master object. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + ldflags + </dt> + <dd><code><code class='datatype'>string</code> MasterObject.ldflags</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Flags suitable for use when linking Pike C modules + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - + master_read_file + </dt> + <dd><code><code class='datatype'>string</code> master_read_file(<code class='datatype'>string</code> <code class='argument'>file</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a file from the master filesystem. + The master filesystem defaults to the system filesystem, + but additional mountpoints may be added via + <code>add_filesystem_handler()</code>. + All file I/O performed by the <code>MasterObject</code> is performed + via this function and its related functions. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_filesystem_handler()</code>, <code>find_handler_for_path()</code>, + <code>master_get_dir()</code>, <code>master_file_stat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + module_defined + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) module_defined(<code class='datatype'>object</code>|<code class='datatype'>program</code> <code class='argument'>mod</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Find the files in which <code>mod</code> is defined, as they may be hidden away in + joinnodes and dirnodes + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>mod</code></dt> + <dd></dd><dd class='body--doc'>The module we are looking for. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>An array of strings with filenames. + (one for each file in a joinnode, or just one otherwise) + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + objects_reverse_lookup + </dt> + <dd><code><code class='datatype'>program</code> objects_reverse_lookup(<code class='datatype'>object</code> <code class='argument'>obj</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the program for <code>obj</code>, if known to the master. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + out_of_date_warning + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> MasterObject.<code class='constant'>out_of_date_warning</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Should Pike complain about out of date compiled files. + 1 means yes and 0 means no. Controlled by the OUT_OF_DATE_WARNING + define. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + program_path_to_name + </dt> + <dd><code><code class='datatype'>string</code> program_path_to_name(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>module_prefix</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>module_suffix</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>object_suffix</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Converts a module path on the form <code class='expr'>"Foo.pmod/Bar.pmod"</code> or + <code class='expr'>"/path/to/pike/lib/modules/Foo.pmod/Bar.pmod"</code> to a module + identifier on the form <code class='expr'>"Foo.Bar"</code>. + If <code>module_prefix</code> or <code>module_suffix</code> are given, they are + prepended and appended, respectively, to the returned string if + it's a module file (i.e. ends with <code class='expr'>".pmod"</code> or + <code class='expr'>".so"</code>). If <code>object_suffix</code> is given, it's appended to the + returned string if it's an object file (i.e. ends with + <code class='expr'>".pike"</code>). + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + programs_reverse_lookup + </dt> + <dd><code><code class='datatype'>string</code> programs_reverse_lookup(<code class='datatype'>program</code> <code class='argument'>prog</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the path for <code>prog</code> in <code>programs</code>, if it got any. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_precompiled_names + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) query_precompiled_names(<code class='datatype'>string</code> <code class='argument'>fname</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns identifiers (e.g. file names) of potentially precompiled + files in priority order. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_precompiled + </dt> + <dd><code><code class='datatype'>string</code> read_precompiled(<code class='datatype'>string</code> <code class='argument'>id</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Given an identifier returned by query_precompiled_names, returns + the precompiled entry. Can assume the entry exists. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method runtime_warning </dt> <dd><code><code class='datatype'>void</code> runtime_warning(<code class='datatype'>string</code> <code class='argument'>subsystem</code>, <code class='datatype'>string</code> <code class='argument'>msg</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>data</code>)</code></dd>
6482: <hr /> <dl class='group--doc'> <dt class='head--type'>Method + runtime_warning + </dt> + <dd><code><code class='datatype'>void</code> runtime_warning(<code class='datatype'>string</code> <code class='argument'>where</code>, <code class='datatype'>string</code> <code class='argument'>what</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Called for every runtime warning. The first argument identifies + where the warning comes from, the second identifies the specific + message, and the rest depends on that. See code below for currently + implemented warnings. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_inhibit_compile_errors + </dt> + <dd><code><code class='datatype'>void</code> set_inhibit_compile_errors(<code class='datatype'>mixed</code> <code class='argument'>behaviour</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the compile error, warning and exception behaviour. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>behaviour</code></dt> + <dd></dd><dd class='body--doc'>The desired behaviour. One of: + <table class='box'><tr><td><code><code class='datatype'>int(0..0)</code></code></td><td>Output compilation errors and warnings to <tt>stderr</tt>. + This is the default behaviour. + </td></tr> + <tr><td><code><code class='datatype'>int(1..1)</code></code></td><td>Inhibit output of compilator diagnostics. + </td></tr> + <tr><td><code><code class='datatype'>function</code>(<code class='datatype'>string</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>:<code class='datatype'>void</code>)</code></td><td>Function to call for compilation errors. Compilation + warnings and exceptions are inhibited. + The function will be called with the same arguments + as those passed to <code>compile_error()</code>. + </td></tr> + <tr><td><code><code class='object unresolved'>CompilationHandler</code></code></td><td>Compilation handler to use for diagnostics. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note that the behaviour is thread local, and is not copied + to new threads when they are created. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_inhibit_compile_errors()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + show_doc + </dt> + <dd><code><code class='datatype'>object</code> show_doc(<code class='datatype'>program</code>|<code class='datatype'>object</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>obj</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Show documentation for the item <code>obj</code> + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>obj</code></dt> + <dd></dd><dd class='body--doc'>The object for which the documentation should be shown + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>an AutoDoc object + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + show_if_constant_errors + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.show_if_constant_errors</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Show compilation warnings from compilation of <code>cpp()</code> + <code class='expr'>#if constant()</code> expressions. + This is typically set via the option <code class='expr'>"--picky-cpp"</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method thread_quanta_exceeded </dt> <dd><code><code class='datatype'>void</code> thread_quanta_exceeded(<code class='object unresolved'>Thread.Thread</code> <code class='argument'>thread</code>, <code class='datatype'>int</code> <code class='argument'>ns</code>)</code></dd>
6524: </dd><dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'>Shouldn't this function be in the compilation handler? </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class RandomInterface</h2> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + want_warnings + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.want_warnings</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>If not zero compilation warnings will be written out on stderr. + </dd></dl> + <dl><dt><h2 class='header'>Class MasterObject.Codec</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><code>Encoder</code> and <code>Decoder</code> rolled into one. This is for mainly + compatibility; there's typically no use combining encoding and + decoding into the same object. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.Codec MasterObject.Codec(<code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>encoded</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The optional argument is the thing to encode; it's passed on to + <code>Encoder</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Decoder + </dt> + <dd><code>inherit Decoder : Decoder</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Encoder + </dt> + <dd><code>inherit Encoder : Encoder</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.CompatResolver</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Resolver of symbols not located in the program being compiled. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_include_path + </dt> + <dd><code><code class='datatype'>void</code> add_include_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for include files. + This is the same as the command line option <tt>-I</tt>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note that the added directory will only be searched when using + < > to quote the included file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_include_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_module_path + </dt> + <dd><code><code class='datatype'>void</code> add_module_path(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>subpath</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for modules. + This is the same as the command line option <tt>-M</tt>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_module_path()</code> + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>path</code></dt> + <dd></dd><dd class='body--doc'>a string containing a path to search for Pike modules. May be a + directory, or a path to a ZIP archive. If a ZIP archive path is + provided, modules will be loaded from a directory, "modules" within + the ZIP archive (see the subpath argument). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>subpath</code></dt> + <dd></dd><dd class='body--doc'>if path is a ZIP archive, this argument will determine the path within + the archive to be searched. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_predefine + </dt> + <dd><code><code class='datatype'>void</code> add_predefine(<code class='datatype'>string</code> <code class='argument'>name</code>, <code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a define (without arguments) which will be implicitly + defined in <code>cpp</code> calls. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_program_path + </dt> + <dd><code><code class='datatype'>void</code> add_program_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a directory to search for programs. + This is the same as the command line option <tt>-P</tt>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>remove_program_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.CompatResolver MasterObject.CompatResolver(<code class='datatype'>mixed</code> <code class='argument'>version</code>, <code class='object unresolved'>CompatResolver</code>|<code class='datatype'>void</code> <code class='argument'>fallback_resolver</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The CompatResolver is initialized with a value that can be + casted into a "%d.%d" string, e.g. a version object. + It can also optionally be initialized with a fallback resolver. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + fallback_resolver + </dt> + <dd><code><code class='object unresolved'>CompatResolver</code> MasterObject.CompatResolver.fallback_resolver</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>If we fail to resolv, try the fallback. + Typical configuration: + <pre>0.6->7.0->7.2-> ... ->master</pre> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_default_module + </dt> + <dd><code><code class='datatype'>mapping</code> get_default_module()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the default module for the <code>CompatResolver</code>. + This is the mapping that corresponds to the <code>predef::</code> + name space for the compatibility level, and is the + value returned by <code>all_constants()</code> for the same. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_predefines + </dt> + <dd><code><code class='datatype'>mapping</code> get_predefines()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns a mapping with the current predefines. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + handle_include + </dt> + <dd><code><code class='datatype'>string</code> handle_include(<code class='datatype'>string</code> <code class='argument'>f</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>int</code> <code class='argument'>local_include</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called whenever an #include directive is + encountered. It receives the argument for #include and should + return the file name of the file to include. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_include()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + handler_root_modules + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>object</code>:<code class='object unresolved'>joinnode</code>) MasterObject.CompatResolver.handler_root_modules</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Lookup from handler module to corresponding root_module. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + instantiate_static_modules + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>) instantiate_static_modules(<code class='datatype'>object</code>|<code class='datatype'>mapping</code> <code class='argument'>static_modules</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Instantiate static modules in the same way that dynamic modules + are instantiated. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + pike_include_path + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) MasterObject.CompatResolver.pike_include_path</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The complete include search path + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + pike_module_path + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) MasterObject.CompatResolver.pike_module_path</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The complete module search path + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + pike_program_path + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) MasterObject.CompatResolver.pike_program_path</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The complete program search path + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_include + </dt> + <dd><code><code class='datatype'>string</code> read_include(<code class='datatype'>string</code> <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read the file specified by <code>handle_include()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>handle_include()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_include_path + </dt> + <dd><code><code class='datatype'>void</code> remove_include_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for include files. + This function performs the reverse operation of <code>add_include_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_include_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_module_path + </dt> + <dd><code><code class='datatype'>void</code> remove_module_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for modules. + This function performs the reverse operation of <code>add_module_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_module_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_predefine + </dt> + <dd><code><code class='datatype'>void</code> remove_predefine(<code class='datatype'>string</code> <code class='argument'>name</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a define from the set that are implicitly defined in + <code>cpp</code> calls. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + remove_program_path + </dt> + <dd><code><code class='datatype'>void</code> remove_program_path(<code class='datatype'>string</code> <code class='argument'>tmp</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a directory to search for programs. + This function performs the reverse operation of <code>add_program_path()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>add_program_path()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv + </dt> + <dd><code><code class='datatype'>mixed</code> resolv(<code class='datatype'>string</code> <code class='argument'>identifier</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>current_handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>current_compat_handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Resolve the <code>identifier</code> expression. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the value of the <code>identifier</code> if it exists, + and <code>UNDEFINED</code> otherwise. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv_base + </dt> + <dd><code><code class='datatype'>mixed</code> resolv_base(<code class='datatype'>string</code> <code class='argument'>identifier</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>current_handler</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>current_compat_handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Look up <code>identifier</code> in the root module. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + resolv_or_error + </dt> + <dd><code><code class='datatype'>mixed</code> resolv_or_error(<code class='datatype'>string</code> <code class='argument'>identifier</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>current_handler</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Same as <code>resolv</code>, but throws an error instead of returning + <code>UNDEFINED</code> if the resolv failed. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + root_module + </dt> + <dd><code><code class='object unresolved'>joinnode</code> MasterObject.CompatResolver.root_module</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Join node of the root modules for this resolver. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + system_module_path + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) MasterObject.CompatResolver.system_module_path</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The pike system module path, not including any set by the user. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.Decoder</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Codec for use with <code>decode_value</code>. This is the decoder + corresponding to <code>Encoder</code>. See that one for more details. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.Decoder MasterObject.Decoder(<code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>fname</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>mkobj</code>, <code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>handler</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + decode_object + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) decode_object(<code class='datatype'>object</code> <code class='argument'>o</code>, <code class='datatype'>mixed</code> <code class='argument'>data</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Restore the state of an encoded object. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>o</code></dt> + <dd></dd><dd class='body--doc'>Object to modify. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>data</code></dt> + <dd></dd><dd class='body--doc'>State information from <code>Encoder()->encode_object()</code>. + The default implementation calls <code class='expr'>o->_decode(data)</code> + if the object has an <code class='expr'>_decode()</code>, otherwise if + <code>data</code> is an array, returns it to indicate that <code>lfun::create()</code> + should be called. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function is called before <code>lfun::create()</code> + in the object has been called, but after <code>lfun::__INIT()</code> + has been called. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an array to indicate to the caller that + <code>lfun::create()</code> should be called with the elements + of the array as arguments. + Returns <code class='expr'>0</code> (zero) to inhibit calling of <code>lfun::create()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Encoder()->encode_object()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + fname + Variable + mkobj + Variable + handler + </dt> + <dd><code><code class='datatype'>void</code>|<code class='datatype'>string</code> MasterObject.Decoder.fname</code> + <code><code class='datatype'>void</code>|<code class='datatype'>int</code> MasterObject.Decoder.mkobj</code> + <code><code class='datatype'>void</code>|<code class='datatype'>object</code> MasterObject.Decoder.handler</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.Describer</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Class used by <code>describe_backtrace()</code> to describe values in backtraces. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + DestructImmediate + </dt> + <dd><code>inherit _static_modules.Builtin.DestructImmediate : DestructImmediate</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.Encoder</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Codec for use with <code>encode_value</code>. It understands all the + standard references to builtin functions, pike modules, and the + main program script. + The format of the produced identifiers are documented here to + allow extension of this class: + The produced names are either strings or arrays. The string + variant specifies the thing to look up according to the first + character: + 'c' Look up in all_constants(). + 's' Look up in _static_modules. + 'r' Look up with resolv(). + 'p' Look up in programs. + 'o' Look up in programs, then look up the result in objects. + 'f' Look up in fc. + In the array format, the first element is a string as above and + the rest specify a series of things to do with the result: + A string Look up this string in the result. + 'm' Get module object in dirnode. + 'p' Do object_program(result). + All lowercase letters and the symbols ':', '/' and '.' are + reserved for internal use in both cases where characters are used + above. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.Encoder MasterObject.Encoder(<code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>encoded</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates an encoder instance. If <code>encoded</code> is specified, it's + encoded instead of being reverse resolved to a name. That's + necessary to encode programs. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + nameof + </dt> + <dd><code><code class='datatype'>string</code>|<code class='datatype'>array</code> nameof(<code class='datatype'>mixed</code> <code class='argument'>what</code>, <code class='datatype'>void</code>|<code class='datatype'>array</code>(<code class='datatype'>object</code>) <code class='argument'>module_object</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>When <code>module_object</code> is set and the name would end with an + <code class='expr'>object_program</code> step (i.e. <code class='expr'>'p'</code>), then drop that + step so that the name corresponds to the object instead. + <code class='expr'><code>module_object</code>[0]</code> will receive the found object. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.Pike_7_8_master</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Pike 7.8 master compatibility interface. + Most of the interface is implemented via mixin, + or overloading by more recent masters. + This interface is used for compatibility with + Pike 7.8. + </dd> + <dt class='head--doc'>Deprecated</dt> + <dd class='body--doc'>Replaced by <code>predef::MasterObject</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_compat_master()</code>, <code>master()</code>, <code>predef::MasterObject</code> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class MasterObject.Pike_8_0_master</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Pike 8.0 master compatibility interface. + Most of the interface is implemented via mixin, + or overloading by more recent masters. + This interface is used for compatibility with + Pike 8.0. + </dd> + <dt class='head--doc'>Deprecated</dt> + <dd class='body--doc'>Replaced by <code>predef::MasterObject</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_compat_master()</code>, <code>master()</code>, <code>predef::MasterObject</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Pike_7_8_master + </dt> + <dd><code>inherit Pike_7_8_master : Pike_7_8_master</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.Version</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Contains version information about a Pike version. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `< + Method + `> + Method + `== + Method + __hash + </dt> + <dd><code><code class='datatype'>int</code> res = <code class='class'>MasterObject.Version()</code> < <code class='class'>v</code></code> + <code><code class='datatype'>int</code> res = <code class='class'>MasterObject.Version()</code> > <code class='class'>v</code></code> + <code><code class='datatype'>int</code> res = <code class='class'>MasterObject.Version()</code> == <code class='class'>v</code></code> + <code><code class='datatype'>int</code> hash_value( MasterObject.Version arg )</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Methods define so that version objects + can be compared and ordered. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + cast + </dt> + <dd><code>(int)MasterObject.Version() (float)MasterObject.Version() (string)MasterObject.Version() (array)MasterObject.Version() (mapping)MasterObject.Version() (multiset)MasterObject.Version()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The version object can be casted into a string. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.Version MasterObject.Version(<code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the version in the object. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + major + Variable + minor + </dt> + <dd><code><code class='datatype'>int</code> MasterObject.Version.major</code> + <code><code class='datatype'>int</code> MasterObject.Version.minor</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The major and minor parts of the version. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.dirnode</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Module node representing a single directory. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>joinnode</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + dirname + Variable + compilation_handler + Variable + name + </dt> + <dd><code><code class='datatype'>string</code> MasterObject.dirnode.dirname</code> + <code><code class='datatype'>object</code>|<code class='datatype'>void</code> MasterObject.dirnode.compilation_handler</code> + <code><code class='datatype'>string</code>|<code class='datatype'>void</code> MasterObject.dirnode.name</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.dirnode MasterObject.dirnode(<code class='datatype'>string</code> <code class='argument'>dirname</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compilation_handler</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>name</code>)</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class MasterObject.joinnode</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Module node holding possibly multiple directories, + and optionally falling back to another level. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>dirnode</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + joined_modules + Variable + compilation_handler + Variable + fallback_module + Variable + name + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>object</code>|<code class='datatype'>mapping</code>) MasterObject.joinnode.joined_modules</code> + <code><code class='datatype'>object</code>|<code class='datatype'>void</code> MasterObject.joinnode.compilation_handler</code> + <code><code class='object unresolved'>joinnode</code>|<code class='datatype'>mapping</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int(0..0)</code>)|<code class='datatype'>void</code> MasterObject.joinnode.fallback_module</code> + <code><code class='datatype'>string</code>|<code class='datatype'>void</code> MasterObject.joinnode.name</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>MasterObject.joinnode MasterObject.joinnode(<code class='datatype'>array</code>(<code class='datatype'>object</code>|<code class='datatype'>mapping</code>) <code class='argument'>joined_modules</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>compilation_handler</code>, <code class='object unresolved'>joinnode</code>|<code class='datatype'>mapping</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int(0..0)</code>)|<code class='datatype'>void</code> <code class='argument'>fallback_module</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>name</code>)</code></dd> + </dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class RandomInterface</h2> </dt><dd> <hr />
6731: <code><code class='datatype'>constant</code> Reporter.<code class='constant'>ERROR</code></code> <code><code class='datatype'>constant</code> Reporter.<code class='constant'>FATAL</code></code></dd> </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class mklibpike</h2> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class __dirnode</h2> </dt><dd> <hr /> <dl class='group--doc'> - + <dt class='head--type'>Inherit + dirnode + </dt> + <dd><code>inherit MasterObject.dirnode : dirnode</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class __joinnode</h2> + </dt><dd> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + joinnode + </dt> + <dd><code>inherit MasterObject.joinnode : joinnode</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class mklibpike</h2> + </dt><dd> + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method parse </dt>
67329: <dd class='body--doc'><code>get_codec_params()</code> </dd></dl> </dd></dl></dd></dl><dl><dt><h2 class='header'>Module _Stdio</h2> - </dt><dd><dl><dt><h2 class='header'>Class _Stdio.Buffer</h2> + </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - + <dd class='body--doc'>Low-level I/O. + This is usually NOT the module you want. + Try <code>Stdio</code> instead. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + IPPROTO_IP + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>IPPROTO_IP</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set IP-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + IPPROTO_TCP + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>IPPROTO_TCP</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set TCP-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + IP_TOS + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>IP_TOS</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set Type Of Service + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_ATTRIB + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_ATTRIB</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for attribute changes on a file. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_DELETE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_DELETE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for deletion of a file. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_EXTEND + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_EXTEND</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for extension events on a file. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_LINK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_LINK</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for changes to a file's link count. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_RENAME + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_RENAME</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for move or rename events on a file. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_REVOKE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_REVOKE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for access revokation (unmount, etc). + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_WRITE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>NOTE_WRITE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor + for writes to a file. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Available on systems that use kqueue. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BIDIRECTIONAL + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file is bi-directional. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BUFFERED + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file is buffered (usually 4KB). + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_IPC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_IPC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file may be used for inter process communication. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_NONBLOCK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file supports nonblocking I/O. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_REVERSE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_REVERSE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Request reversed operation. + Used as argument to <code>Stdio.File()->pipe()</code>, when + <code>PROP_BIDIRECTIONAL</code> hasn't been specified, to + request the direction of the resulting pipe to + reversed. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SEND_FD + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The <code>Stdio.File</code> object might support the <code>Stdio.File()->send_fd()</code> + operation. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code>, <code>Stdio.File()->send_fd()</code>, + <code>Stdio.File()->receive_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SHUTDOWN + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file supports shutting down transmission in either + direction. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->close()</code>, <code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_TTY + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_TTY</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The <code>Stdio.File</code> object supports tty operations. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This constant is only present on platforms where pseudo tty + (aka pty) operations are available, and may thus be used to + detect whether such operations should be attempted. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + SOL_SOCKET + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>SOL_SOCKET</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set socket-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + SO_KEEPALIVE + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>SO_KEEPALIVE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control TCP/IP keep-alive packets. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + TCP_NODELAY + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>TCP_NODELAY</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control Nagle's Algorithm. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + XATTR_CREATE + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>XATTR_CREATE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a pure + create, which will fail if the attribute already exists. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + XATTR_REPLACE + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>XATTR_REPLACE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a replace, + which will fail the the attribute does not already exists. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_OOB__ + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>__HAVE_OOB__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Exists and has the value 1 if OOB operations are available. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In Pike 7.5 and later OOB operations are always present. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_SEND_FD__ + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>__HAVE_SEND_FD__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Support for sending of file descriptors over + <code>Stdio.File()->pipe()</code> objects with <code>PROP_SEND_FD</code> + capability is supported. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->send_fd()</code>, <code>Stdio.File()->receive_fd()</code>, + <code>Stdio.File()->read()</code>, <code>Stdio.File()->write()</code>, + <code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __OOB__ + </dt> + <dd><code><code class='datatype'>constant</code> _Stdio.<code class='constant'>__OOB__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Implementation level of nonblocking I/O OOB support. + <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Nonblocking OOB support is not supported. + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>Nonblocking OOB works a little. + </td></tr> + <tr><td><code><code class='key'>2</code></code></td><td>Nonblocking OOB almost works. + </td></tr> + <tr><td><code><code class='key'>3</code></code></td><td>Nonblocking OOB works as intended. + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Unknown level of nonblocking OOB support. + </td></tr> + </table>This constant only exists when OOB operations are + available, i.e. when <code>__HAVE_OOB__</code> is 1. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_all_active_fd + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_all_active_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the id of all the active file descriptors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + gethostip + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mapping</code>) gethostip()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the IP addresses of the host. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns a mapping that maps interface name to a mapping with + more information about that interface. That information mapping + looks as follows. + <table class='box'><tr><td><code><code class='key'>"ips"</code> : <code class='datatype'>array</code>(<code class='datatype'>string</code>)</code></td><td>A list of all IP addresses bound to this interface. + </td></tr> + </table></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + getprotobyname + </dt> + <dd><code><code class='datatype'>int</code> getprotobyname(<code class='datatype'>string(8bit)</code> <code class='argument'>name</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the protocol number of the protocol <code class='expr'>name</code>. + This calls the POSIX function getprotobyname. + If the protocol cannot be found an error is thrown. + </dd></dl> + <dl><dt><h2 class='header'>Enum _Stdio.FileModeFlags</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File mode flags returned by <code>Fd()->mode()</code>. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_APPEND + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_APPEND</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for appending. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_CREATE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_CREATE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Create a new file if it didn't exist earlier. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_EXCLUSIVE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_EXCLUSIVE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Exclusive access to the file. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_NONBLOCKING + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_NONBLOCKING</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File opened in nonblocking mode. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_READ + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_READ</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for reading. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_TRUNC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_TRUNC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Truncate the file on open. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_WRITE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>FILE_WRITE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for writing. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Enum _Stdio.FilePropertyFlags</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File properties for use with eg <code>Fd()->pipe()</code>, + and returned by eg <code>Fd()->mode()</code>. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BIDIRECTIONAL + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports both sending and receiving. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BUFFERED + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File has internal buffering. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_IPC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_IPC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File can be used for interprocess communication. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_NONBLOCK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports nonblocking operation. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SEND_FD + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File is capable of sending open file descriptors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SHUTDOWN + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports unidirectional close. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_TTY + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> _Stdio.<code class='constant'>PROP_TTY</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports tty operations. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class _Stdio.Buffer</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>A buffer to use as input or buffering when doing I/O. It is similar to <code>String.Buffer</code>, but can only contain 8bit data and is designed for protocol parsing. It is optimized for reading from
68479: position of the buffer. </dd></dl> </dd></dl></dd></dl><dl><dt><h2 class='header'>Class _Stdio.Fd</h2> - </dt><dd> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Low level I/O operations. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd_ref</code> + </dd></dl> <hr /> <dl class='group--doc'> - + <dt class='head--type'>Variable + _errno + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>int(0..)</code> _Stdio.Fd._errno</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Variable containing the internal value returned by <code>errno()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>errno()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _fd + </dt> + <dd><code><code class='object unresolved'>Fd</code> _Stdio.Fd._fd</code></dd> + + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Read only + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _read_callback + Variable + _write_callback + Variable + _read_oob_callback + Variable + _write_oob_callback + Variable + _fs_event_callback + </dt> + <dd><code><code class='datatype'>mixed</code> _Stdio.Fd._read_callback</code> + <code><code class='datatype'>mixed</code> _Stdio.Fd._write_callback</code> + <code><code class='datatype'>mixed</code> _Stdio.Fd._read_oob_callback</code> + <code><code class='datatype'>mixed</code> _Stdio.Fd._write_oob_callback</code> + <code><code class='datatype'>mixed</code> _Stdio.Fd._fs_event_callback</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Callback functions installed by <code>Stdio.File()->set_callbacks()</code> et al. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - + close + </dt> + <dd><code><code class='datatype'>int</code> close()</code> + <code><code class='datatype'>int</code> close(<code class='datatype'>string</code> <code class='argument'>direction</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Close a file or stream. + If direction is not specified, both the read and the write + direction are closed. Otherwise only the directions specified is + closed. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> if the file or stream now is closed in + all directions, and <code class='expr'>0</code> otherwise. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An exception is thrown if an I/O error occurs. + The default behaviour for sockets is typically to flush buffered + data in the background, but this can be changed with <code>linger()</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>close()</code> has no effect if this file object has been associated + with an already opened file, i.e. if <code>open()</code> was given an + integer as the first argument. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>linger()</code>, <code>open()</code>, <code>open_socket()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + connect + </dt> + <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>)</code> + <code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code> <code class='argument'>src_port</code>)</code> + <code><code class='datatype'>string(8bit)</code>|<code class='datatype'>int(0..0)</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_port</code>, <code class='datatype'>string(8bit)</code> <code class='argument'>data</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a TCP/IP connection to the specified destination. + In nonblocking mode, success is indicated with the write-callback, + and failure with the close-callback or the read_oob-callback. + If the <code>data</code> argument is included the socket will use + TCP_FAST_OPEN if available, if not the data will not be + sent. In the data case the function either returns the data + that has not been sent (only one packet can be sent with this + option) or 0 if the connection failed immediately. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> or the remaining <code class='expr'>data</code> on success, and + <code class='expr'>0</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set + to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded + as a connection failure. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + connect_unix + </dt> + <dd><code><code class='datatype'>bool</code> connect_unix(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a UNIX domain socket connection to the specified destination. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>filename</code></dt> + <dd></dd><dd class='body--doc'>Filename to create. + In nonblocking mode, success is indicated with the write-callback, + and failure with the close-callback or the read_oob-callback. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set + to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded + as a connection failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) + prior to Pike 7.8.334. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>_Stdio.Fd _Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> + <code>_Stdio.Fd _Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code>_Stdio.Fd _Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code> + <code>_Stdio.Fd _Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code> + <code>_Stdio.Fd _Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>See <code>open()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + dup + </dt> + <dd><code><code class='object unresolved'>Stdio.Fd</code> dup()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Duplicate the file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>dup2()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + dup2 + </dt> + <dd><code><code class='datatype'>int</code> dup2(<code class='object unresolved'>Stdio.File</code> <code class='argument'>to</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Duplicate a file over another. + This function works similarly to <code>assign()</code>, but instead of making + the argument a reference to the same file, it creates a new file + with the same properties and places it in the argument. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>to</code> need not be open, in which + case a new fd is allocated. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note also that <code>to</code> is also assigned to the same backend (if any) + as this object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>assign()</code>, <code>dup()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + errno + </dt> + <dd><code><code class='datatype'>int</code> errno()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the errno for the latest failed file operation. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + fd_factory + </dt> + <dd><code><code class='object unresolved'>Fd</code> fd_factory()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Factory creating <code>Stdio.Fd</code> objects. + This function is called by <code>openat()</code>, <code>pipe()</code>, <code>dup()</code> + and other functions creating new file objects. + The default implementation calls <code class='expr'>object_program(this_object())()</code> + to create the new object, and returns the <code>Fd</code> inherit in it. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note that this function must return the <code>Fd</code> inherit in the object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.Port()->fd_factory()</code>, <code>openat()</code>, <code>pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_dir + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) get_dir(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>path</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get directory contents relative to an open directory. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>path</code></dt> + <dd></dd><dd class='body--doc'>Path relative to the open directory. Defaults to the + directory itself. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an array of filenames. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>predef::get_dir()</code>, <code>statat()</code>, <code>openat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + getxattr + </dt> + <dd><code><code class='datatype'>string</code> getxattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the value of a specified attribute, or 0 if it does not exist + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + grantpt + </dt> + <dd><code><code class='datatype'>string</code> grantpt()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>If this file has been created by calling <code>openpt()</code>, return the + filename of the associated pts-file. This function should only be + called once. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the filename of the corresponding pts. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function is only available on some platforms. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + is_open + </dt> + <dd><code><code class='datatype'>int</code> is_open()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns true if the file is open. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>If the file is a socket that has been closed from the remote side, + this function might still return true. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Most methods can't be called for a file descriptor that isn't + open. Notable exceptions <code>errno</code>, <code>mode</code>, and the set and query + functions for callbacks and backend. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + linger + </dt> + <dd><code><code class='datatype'>bool</code> linger(<code class='datatype'>int(-1..65535)</code>|<code class='datatype'>void</code> <code class='argument'>seconds</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the socket linger behaviour on <code>close()</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>seconds</code></dt> + <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td>Reset to default behaviour. This typically means that + <code>close()</code> will return immediately, but any buffered + data will still be sent if possible. + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>Terminate the connection immediately on <code>close()</code>, + and discard any buffered data. + </td></tr> + <tr><td><code><code class='key'>(1..65535)</code></code></td><td>Have <code>close()</code> wait for at most <code>seconds</code> seconds + for any buffered data to be sent after which the + connection is terminated. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This operation is only valid on sockets. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function was not available in Pike 7.8.775 and earlier. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>close()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + listxattr + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) listxattr()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return an array of all extended attributes set on the file + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + lock + </dt> + <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> lock()</code> + <code><code class='object unresolved'>Stdio.FileLockKey</code> lock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Makes an exclusive file lock on this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>trylock()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + mode + </dt> + <dd><code><code class='object unresolved'>FileModeFlags</code>|<code class='object unresolved'>FilePropertyFlags</code> mode()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the open mode and capabilities for the file. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an <code>`|()</code> of the following flags: + <table class='box'><tr><td><code><code class='key'>0x1000</code></code></td><td><code>FILE_READ</code> + </td></tr> + <tr><td><code><code class='key'>0x2000</code></code></td><td><code>FILE_WRITE</code> + </td></tr> + <tr><td><code><code class='key'>0x4000</code></code></td><td><code>FILE_APPEND</code> + </td></tr> + <tr><td><code><code class='key'>0x8000</code></code></td><td><code>FILE_CREATE</code> + </td></tr> + <tr><td><code><code class='key'>0x0100</code></code></td><td><code>FILE_TRUNC</code> + </td></tr> + <tr><td><code><code class='key'>0x0200</code></code></td><td><code>FILE_EXCLUSIVE</code> + </td></tr> + <tr><td><code><code class='key'>0x0400</code></code></td><td><code>FILE_NONBLOCKING</code> + </td></tr> + <tr><td><code><code class='key'>0x0080</code></code></td><td><code>PROP_TTY</code> + </td></tr> + <tr><td><code><code class='key'>0x0040</code></code></td><td><code>PROP_SEND_FD</code> + </td></tr> + <tr><td><code><code class='key'>0x0010</code></code></td><td><code>PROP_BIDIRECTIONAL</code> + </td></tr> + <tr><td><code><code class='key'>0x0008</code></code></td><td><code>PROP_BUFFERED</code> + </td></tr> + <tr><td><code><code class='key'>0x0004</code></code></td><td><code>PROP_SHUTDOWN</code> + </td></tr> + <tr><td><code><code class='key'>0x0002</code></code></td><td><code>PROP_NONBLOCK</code> + </td></tr> + <tr><td><code><code class='key'>0x0001</code></code></td><td><code>PROP_IPC</code> + </td></tr> + </table> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In some versions of Pike 7.8 the <tt>PROP_</tt> flags were + filtered from the result. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + open + </dt> + <dd><code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code> + <code><code class='datatype'>int</code> open(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a file, or use an existing fd. + If <code>filename</code> is given, attempt to open the named file. If <code>fd</code> + is given instead, it should be the file descriptor for an already + opened file, which will then be used by this object. + <code>mode</code> describes how the file is opened. It's a case-insensitive + string consisting of one or more of the following letters: + <dl class='group--doc'><dt>"r"</dt> + <dd>Open for reading. + </dd> + <dt>"w"</dt> + <dd>Open for writing. + </dd> + <dt>"a"</dt> + <dd>Append new data to the end. + </dd> + <dt>"c"</dt> + <dd>Create the file if it doesn't exist already. + </dd> + <dt>"t"</dt> + <dd>Truncate the file to zero length if it already contains data. + Use only together with <code class='expr'>"w"</code>. + </dd> + <dt>"x"</dt> + <dd>Open exclusively - the open fails if the file already exists. + Use only together with <code class='expr'>"c"</code>. Note that it's not safe to + assume that this is atomic on some systems. + </dd> + </dl><code>access</code> specifies the permissions to use if a new file is + created. It is a UNIX style permission bitfield: + <dl class='group--doc'><dt>0400</dt> + <dd>User has read permission. + </dd> + <dt>0200</dt> + <dd>User has write permission. + </dd> + <dt>0100</dt> + <dd>User has execute permission. + </dd> + <dt>0040</dt> + <dd>Group has read permission. + </dd> + <dt>0020</dt> + <dd>Group has write permission. + </dd> + <dt>0010</dt> + <dd>Group has execute permission. + </dd> + <dt>0004</dt> + <dd>Others have read permission. + </dd> + <dt>0002</dt> + <dd>Others have write permission. + </dd> + <dt>0001</dt> + <dd>Others have execute permission. + </dd> + </dl>It's system dependent on which of these bits that are actually + heeded. If <code>access</code> is not specified, it defaults to + <code class='expr'>00666</code>, but note that on UNIX systems it's masked with the + process umask before use. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns nonzero on success and <code class='expr'>0</code> (zero) on failure. If + there is a failure then <code>errno</code> returns the error code. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>close()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + open_socket + </dt> + <dd><code><code class='datatype'>bool</code> open_socket(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>addr</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + openat + </dt> + <dd><code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> + <code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a file relative to an opened directory. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns a new file object on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code>, <code>statat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + openpt + </dt> + <dd><code><code class='datatype'>int</code> openpt(<code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open the master end of a pseudo-terminal pair. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>grantpt()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + peek + </dt> + <dd><code><code class='datatype'>int(-1..1)</code> peek()</code> + <code><code class='datatype'>int(-1..1)</code> peek(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code> + <code><code class='datatype'>int(-1..1)</code> peek(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>, <code class='datatype'>int</code> <code class='argument'>not_eof</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Check if there is data available to read, + or wait some time for available data to read. + More specifically, a later call to <code>read()</code> will return + immediately, either due to data being present, or due to + some error (eg if a socket has been closed). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>timeout</code></dt> + <dd></dd><dd class='body--doc'>Timeout in seconds. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>not_eof</code></dt> + <dd></dd><dd class='body--doc'>Flag for specifying handling of end of file. + The following values are currently defined: + <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Traditional (and default) behaviour. Return <code class='expr'>1</code> + at EOF. + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>Regard EOF as an error. Return <code class='expr'>-1</code> and set <code>errno()</code> + to return <code class='expr'>EPIPE</code> at EOF. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>1</code></code></td><td>There is data available to <code>read()</code>, or <code>not_eof</code> is + <code class='expr'>0</code> (zero) and we're at EOF. A later call to + <code>read()</code> will not block. + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>There is no data available (ie timeout). + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Error condition. The error code returned by <code>errno()</code> + has been updated. + </td></tr> + </table> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>errno()</code>, <code>read()</code> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The function may be interrupted prematurely + of the timeout (due to signals); + check the timing manually if this is imporant. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + pipe + </dt> + <dd><code><code class='object unresolved'>Stdio.File</code> pipe()</code> + <code><code class='object unresolved'>Stdio.File</code> pipe(<code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + proxy + </dt> + <dd><code><code class='datatype'>void</code> proxy(<code class='object unresolved'>Stdio.File</code> <code class='argument'>from</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Starts a thread that asynchronously copies data from <code>from</code> + to this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.sendfile()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_address + </dt> + <dd><code><code class='datatype'>string</code> query_address()</code> + <code><code class='datatype'>string</code> query_address(<code class='datatype'>bool</code> <code class='argument'>local</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get address and port of a socket end-point. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>local</code></dt> + <dd></dd><dd class='body--doc'>If the argument <code>local</code> is not specified, or is <code class='expr'>0</code> + (zero), the remote end-point is returned. Otherwise, if <code>local</code> + is <code class='expr'>1</code>, the local end-point is returned. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns the address and port of a socket end-point + on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or + <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). IPv6 addresses + may use the contracted syntax. + If this file is not a socket, is not connected, or some other + error occurs, <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will + return the error code. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error is thrown if the socket (or file) isn't open. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>connect()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_backend + </dt> + <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the backend used for the callbacks. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_backend</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_fd + </dt> + <dd><code><code class='datatype'>int</code> query_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the file descriptor number associated with this object. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_mtu + </dt> + <dd><code><code class='datatype'>int</code> query_mtu()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get the Max Transfer Unit for the object (if any). + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td>Returns <code class='expr'>-1</code> if the object is not a socket or + if the mtu is unknown. + </td></tr> + <tr><td><code><code class='key'>(1..)</code></code></td><td>Returns a positive value with the mtu on success. + </td></tr> + </table></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>string(8bit)</code> read()</code> + <code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> + <code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read data from a file or a stream. + Attempts to read <code>len</code> bytes from the file, and return it as a + string. Less than <code>len</code> bytes can be returned if: + <ul> + <li>end-of-file is encountered for a normal file, or + </li><li>it's a stream that has been closed from the other end, or + </li><li>it's a stream in nonblocking mode, or + </li><li>it's a stream and <code>not_all</code> is set, or + </li><li><code>not_all</code> isn't set and an error occurred (see below). + </li></ul>If <code>not_all</code> is nonzero, <code>read()</code> does not try its best to read + as many bytes as you have asked for, but merely returns as much as + the system read function returns. This is mainly useful with + stream devices which can return exactly one row or packet at a + time. If <code>not_all</code> is used in blocking mode, <code>read()</code> only + blocks if there's no data at all available. + If something goes wrong and <code>not_all</code> is set, zero is returned. + If something goes wrong and <code>not_all</code> is zero or left out, then + either zero or a string shorter than <code>len</code> is returned. If the + problem persists then a later call to <code>read()</code> fails and returns + zero, however. + If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. That includes an end due to end-of-file or remote + close. + If no arguments are given, <code>read()</code> reads to the end of the file + or stream. + If any file descriptors have been sent by the other side of the + stream, <code>receive_fd()</code> will be called once for every sent file + descriptor. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading + when nonblocking mode is used. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>When at the end of a file or stream, repeated calls to <code>read()</code> + will return the empty string since it's not considered an error. + The empty string is never returned in other cases, unless nonblocking + mode is used or <code>len</code> is zero. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_oob()</code>, <code>write()</code>, <code>receive_fd()</code>, <code>send_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>System.Memory</code> <code class='argument'>dst</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code> at offset + <code>offset</code>. Tries to read as many bytes as buffer space available. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and + <code>errno()</code> will return the corresponding error code. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>dst</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code>. Tries to + read as many bytes as buffer space available. + Will advance the write position in <code>dst</code> by the number of bytes + read. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and + <code>errno()</code> will return the corresponding error code. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_oob + </dt> + <dd><code><code class='datatype'>string</code> read_oob()</code> + <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> + <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Attempts to read <code>len</code> bytes of out-of-band data from the stream, + and returns it as a string. Less than <code>len</code> bytes can be returned + if: + <ul> + <li>the stream has been closed from the other end, or + </li><li>nonblocking mode is used, or + </li><li><code>not_all</code> is set, or + </li><li><code>not_all</code> isn't set and an error occurred (see below). + </li></ul>If <code>not_all</code> is nonzero, <code>read_oob()</code> only returns as many bytes + of out-of-band data as are currently available. + If something goes wrong and <code>not_all</code> is set, zero is returned. + If something goes wrong and <code>not_all</code> is zero or left out, then + either zero or a string shorter than <code>len</code> is returned. If the + problem persists then a later call to <code>read_oob()</code> fails and + returns zero, however. + If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. That includes an end due to remote close. + If no arguments are given, <code>read_oob()</code> reads to the end of the + stream. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It is not guaranteed that all out-of-band data sent from the + other end is received. Most streams only allow for a single byte + of out-of-band data at a time. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading + when nonblocking mode is used. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>When at the end of a file or stream, repeated calls to <code>read()</code> + returns the empty string since it's not considered an error. The + empty string is never returned in other cases, unless nonblocking + mode is used or <code>len</code> is zero. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code>, <code>write_oob()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + receive_fd + </dt> + <dd><code><code class='datatype'>void</code> receive_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remote file descriptor reception handler. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>fd</code></dt> + <dd></dd><dd class='body--doc'>File descriptor received from the remote end of a <code>pipe()</code>. + This object has been created by <code>fd_factory()</code>. + This function is called from <code>read()</code> when a remote file + descriptor has been received over a <code>PROP_SEND_FD</code> + capable <code>pipe()</code>. + The default implementation is just a prototype. + Overload this function to enable reception of + remote file descriptors. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The capability of sending and receiving remote file + descriptors is only available on some operating systems. + This capability is indicated by the precence of <code>__HAVE_SEND_FD__</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>send_fd()</code>, <code>read()</code>, <code>fd_factory()</code>, <code>__HAVE_SEND_FD__</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + release_fd + </dt> + <dd><code><code class='datatype'>int</code> release_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the file descriptor number associated with this object, in + addition to releasing it so that this object behaves as if closed. + Other settings like callbacks and backend remain intact. + <code>take_fd</code> can later be used to reinstate the file descriptor so + that the state is restored. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_fd()</code>, <code>take_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + removexattr + </dt> + <dd><code><code class='datatype'>void</code> removexattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove the specified extended attribute. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + seek + </dt> + <dd><code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>)</code> + <code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>, <code class='datatype'>string</code> <code class='argument'>whence</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The seek() function repositions the offset of the open file + associated with the file descriptor fd to the argument <code>offset</code> + according to the directive <code>whence</code> as follows: + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_SET</code></code></td><td>The offset is set to <code>offset</code> bytes. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_CUR</code></code></td><td>The offset is set to its current location plus <code>offset</code> bytes. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_END</code></code></td><td>The offset is set to the size of the file plus <code>offset</code> bytes. + </td></tr> + </table>If <code>whence</code> is not specified it is SEEK_SET if <code>offset</code> is + positive, and if <code>offset</code> is negative SEEK_END. + The seek() function on most operating systems allows the file + offset to be set beyond the end of the file (but this does not + change the size of the file). If data is later written at this + point, subsequent reads of the data in the gap (a "hole") return + null bytes ('\0') until data is actually written into the gap. + Seeking file data and holes + Stdio.SEEK_DATA and Stdio.SEEK_HOLE are nonstandard extensions + present in Linux, Solaris, FreeBSD, and DragonFly BSD; they are + proposed for inclusion in the next POSIX revision. + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_DATA</code></code></td><td>Adjust the file offset to the next location in the file greater + than or equal to offset containing data. If offset points to + data, then the file offset is set to offset. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_HOLE</code></code></td><td>Adjust the file offset to the next hole in the file greater than + or equal to offset. If offset points into the middle of a hole, + then the file offset is set to offset. If there is no hole past + offset, then the file offset is adjusted to the end of the file + (i.e., there is an implicit hole at the end of any file). + </td></tr> + </table>In both of the above cases, seek() fails if offset points past the + end of the file. + These operations allow applications to map holes in a sparsely + allocated file. This can be useful for applications such as file + backup tools, which can save space when creating backups and + preserve holes, if they have a mechanism for discovering holes. + For the purposes of these operations, a hole is a sequence of + zeros that (normally) has not been allocated in the underlying + file storage. However, a filesystem is not obliged to report + holes, so these operations are not a guaranteed mechanism for + mapping the storage space actually allocated to a file. + (Furthermore, a sequence of zeros that actually has been written + to the underlying storage may or may not be reported as a hole.) + In the simplest implementation, a filesystem can support the + operations by making SEEK_HOLE always return the offset of the end + of the file, and making SEEK_DATA always return offset (i.e., even + if the location referred to by offset is a hole, it can be + considered to consist of data that is a sequence of zeros). + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Upon successful completion, seek() returns the resulting offset + location as measured in bytes from the beginning of the file. On + error, the value (off_t) -1 is returned and <code>errno</code> is set to + indicate the error. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>tell()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + seek + </dt> + <dd><code><code class='modifier'>variant</code> <code class='deprecated'>__deprecated__</code> <code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>unit</code>, <code class='datatype'>int</code> <code class='argument'>mult</code>)</code> + <code><code class='modifier'>variant</code> <code class='deprecated'>__deprecated__</code> <code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>unit</code>, <code class='datatype'>int</code> <code class='argument'>mult</code>, <code class='datatype'>int</code> <code class='argument'>add</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Seek to a specified offset in a file. + If <code>mult</code> or <code>add</code> are specified, <code>pos</code> is calculated as + <code class='expr'><code>pos</code> = <code>unit</code>*<code>mult</code> + <code>add</code></code>. + If <code>pos</code> is negative then it is relative to the end of the file, + otherwise it's an absolute offset from the start of the file. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the new offset, or <code class='expr'>-1</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The arguments <code>mult</code> and <code>add</code> are considered obsolete, and + should not be used. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>tell()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + send_fd + </dt> + <dd><code><code class='datatype'>void</code> send_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Queues an open file descriptor for sending to the other end of a stream. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The actual sending is performed at the next successful call + to <code>write()</code>, this is due to limitations in the system calls. + This means that it isn't possible to send a file descriptor + without also sending some in-band data. + This operation is only supported on <code>pipe()</code>'s created with + <code>PROP_SEND_FD</code>. + This function is not available on all operating systems, check + for <code>__HAVE_SEND_FD__</code>. + The queue is emptied on successful <code>write()</code> and when the + write direction is <code>close()</code>'d. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>receive_fd()</code>, <code>write()</code>, <code>pipe()</code>, <code>read()</code>, <code>__HAVE_SEND_FD__</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_backend + </dt> + <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the backend used for the callbacks. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The backend keeps a reference to this object only when it is in + callback mode. So if this object hasn't got any active callbacks + and it runs out of other references, it will still be destructed + quickly (after closing, if necessary). + Also, this object does not keep a reference to the backend. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_backend</code>, <code>set_nonblocking</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_fs_event_callback</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_blocking + </dt> + <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Sets this file to blocking operation. + This is the inverse operation of <code>set_nonblocking()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_nonblocking()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_buffer + </dt> + <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set internal socket buffer. + This function sets the internal buffer size of a socket or stream. + The second argument allows you to set the read or write buffer by + specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It is not guaranteed that this function actually does anything, + but it certainly helps to increase data transfer speed when it does. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_close_on_exec + </dt> + <dd><code><code class='datatype'>void</code> set_close_on_exec(<code class='datatype'>bool</code> <code class='argument'>yes_no</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Marks the file as to be closed in spawned processes. + This function determines whether this file will be closed when + calling exec(). + Default is that the file WILL be closed on exec except for + stdin, stdout and stderr. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Process.create_process()</code>, <code>exec()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_keepalive + </dt> + <dd><code><code class='datatype'>bool</code> set_keepalive(<code class='datatype'>bool</code> <code class='argument'>on_off</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Equivalent to setsockopt(Stdio.SO_KEEPALIVE, on_off), but will set errno + if SO_KEEPALIVE is not supported, rather than issuing a compilation error + for the missing constant. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_nodelay + </dt> + <dd><code><code class='datatype'>bool</code> set_nodelay(<code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>state</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Control Nagle's Algorithm (RFC 896) + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>state</code></dt> + <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Return to the normal state of using Nagle's Algorithm + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>(default) Disable Nagling - small writes will not be queued. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This operation is only valid on sockets. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>setsockopt() + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_nonblocking + </dt> + <dd><code><code class='datatype'>void</code> set_nonblocking()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Sets this file to nonblocking operation. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Nonblocking operation is not supported on all Stdio.File objects. + Notably it is not guaranteed to be supported on objects returned + by <code>pipe()</code> unless <code>PROP_NONBLOCK</code> was specified in the call + to <code>pipe()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_blocking()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + setsockopt + </dt> + <dd><code><code class='datatype'>bool</code> setsockopt(<code class='datatype'>int</code> <code class='argument'>level</code>, <code class='datatype'>int</code> <code class='argument'>opt</code>, <code class='datatype'>int</code> <code class='argument'>state</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set socket options like Stdio.SO_KEEPALIVE. This function is always + available; the presence or absence of the option constants indicates + availability of those features. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>1 if successful, 0 if not (and sets errno()) + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_keepalive()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + setxattr + </dt> + <dd><code><code class='datatype'>void</code> setxattr(<code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the attribute <code>attr</code> to the value <code>value</code>. + The flags parameter can be used to refine the semantics of the operation. + <code>Stdio.XATTR_CREATE</code> specifies a pure create, which + fails if the named attribute exists already. + <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which + fails if the named attribute does not already exist. + By default (no flags), the extended attribute will be created if need be, + or will simply replace the value if the attribute exists. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>1 if successful, 0 otherwise, setting errno. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + stat + </dt> + <dd><code><code class='object unresolved'>Stat</code> stat()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get status for an open file. + This function returns the same information as the function + <code>file_stat()</code>, but for the file it is called in. If file is not + an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned + if file is a pipe or socket. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>file_stat()</code>, <code>statat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + statat + </dt> + <dd><code><code class='object unresolved'>Stat</code> statat(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get status for a file relative an open directory. + This function returns the same information as the function + <code>file_stat()</code>, but relative to the file it is called in. If file is not + an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned + if file is a pipe or socket. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>file_stat()</code>, <code>stat()</code>, <code>openat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + sync + </dt> + <dd><code><code class='datatype'>bool</code> sync()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Flush buffers to disk. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) and sets errno on failure. + Returns <code class='expr'>1</code> on success. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + take_fd + </dt> + <dd><code><code class='datatype'>void</code> take_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Rehooks the given file descriptor number to be associated with + this object. As opposed to using <code>open</code> with a file descriptor + number, it will be closed by this object upon destruct or when + <code>close</code> is called. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>release_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method tcdrain </dt> <dd><code><code class='datatype'>bool</code> tcdrain()</code></dd>
68647: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>tcgetattr()</code>, <code>tcsetattr()</code> </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + tell + </dt> + <dd><code><code class='datatype'>int</code> tell()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the current offset in the file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>seek()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + truncate + </dt> + <dd><code><code class='datatype'>bool</code> truncate(<code class='datatype'>int</code> <code class='argument'>length</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Truncate a file. + Truncates the file to the specified length <code>length</code>. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + trylock + </dt> + <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> trylock()</code> + <code><code class='object unresolved'>Stdio.FileLockKey</code> trylock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Attempts to place a file lock on this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>lock()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + unlinkat + </dt> + <dd><code><code class='datatype'>int</code> unlinkat(<code class='datatype'>string</code> <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a file or directory relative to an open file. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>rm()</code>, <code>openat()</code>, <code>statat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + write + </dt> + <dd><code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code> + <code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code> + <code><code class='datatype'>int</code> write(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code>|<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Write data to a file or a stream. + If there are any file descriptors that have been queued for sending + (with <code>send_fd()</code>), they will be sent. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>data</code></dt> + <dd></dd><dd class='body--doc'>Data to write. + If <code>data</code> is an array of strings, they are written in sequence. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>format</code></dt> + <dd></dd> + <dt class='head--doc'>Parameter <code class='parameter'>extras</code></dt> + <dd></dd><dd class='body--doc'>If more than one argument is given, <code>sprintf()</code> is used to format + them using <code>format</code>. If <code>format</code> is an array, the strings in it + are concatenated and the result is used as format string. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>offset</code></dt> + <dd></dd><dd class='body--doc'>The offset in data to start writing from. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Writes <code>data</code> and returns the number of bytes that were + actually written. + <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>The number of bytes successfully written to the OS buffers. + This can be less than the size of the given data if eg: + <ul> + <li>Some data was written successfully and then something went + wrong. + If only some data was written due to an error and that error + persists, then a later call to <code>write()</code> will fail and return + <code class='expr'>-1</code>. + </li><li>Nonblocking mode is used and not all data could be written + without blocking. + </li></ul> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>No bytes were written. This may be due to + <ul> + <li><code>data</code> or the formatted data being the empty string. + </li><li>Nonblocking mode is used and no data could be written + without blocking. + </li></ul> + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Something went wrong and no bytes were written. + </td></tr> + </table>If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Writing of wide strings is not supported. You have to encode the + data somehow, e.g. with <code>string_to_utf8</code> or with one of the + charsets supported by <code>Charset.encoder</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The variant of this function using a buffer object does not release + the interpreter lock. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + write_oob + </dt> + <dd><code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Write out-of-band data to a stream. + Writes out-of-band data to a stream and returns how many bytes + that were actually written. It can be less than the size of the + given data if some data was written successfully and then + something went wrong. + -1 is returned if something went wrong and no bytes were written. + If only some data was written due to an error and that error + persists, then a later call to <code>write_oob()</code> fails and returns + -1. + If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. + If more than one argument is given, <code>sprintf()</code> is used to format + them. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It is not guaranteed that all out-of-band data sent from the + other end is received. Most streams only allow for a single byte + of out-of-band data at a time. Some streams sends the rest of + the data as ordinary data. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_oob()</code>, <code>write()</code> + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class _Stdio.Fd_ref</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Proxy class that contains stub functions + that call the corresponding functions in + <code>Fd</code>. + Used by <code>Stdio.File</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _fd + </dt> + <dd><code><code class='object unresolved'>Fd</code> _Stdio.Fd_ref._fd</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Object to which called functions are relayed. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Fd + </dt> + <dd><code>inherit Fd : Fd</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Fake inherit to propagate the documentation + from <code>_Stdio.Fd</code>. + </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class _Stdio.UDP</h2> </dt><dd>

autodoc.git/ traditional_manual/ chapter_21.html

2020-06-10

2020-06-10 21:48:37 by Henrik Grubbström (Grubba) <grubba@grubba.org>