Pike has a builtin C-style preprocessor. It works similar to the ANSI-C preprocessor but has a few extra features. These and the default set of preprocessor macros are described here.

The preprocessor is usually accessed via MasterObject->compile_file() or MasterObject->compile_string(), but may be accessed directly by calling cpp().

compile(), cpp(), CompilerEnvironment.CPP

This is the default namespace and contains lots of global symbols.

The version of FUSE

Root handles in the Windows registry.

These constants are only available on Win32 systems.

RegGetValue(), RegGetValues(), RegGetKeyNames()

Create a class that acts as a proxy for the specified program.

Program to generate a proxy for.

The generated class will have the same symbols (public and private) with the same types as in p, where accesses to these will proxy the access to the same symbol in the proxied (aka wrapped) object. With the following exceptions:

protected void create(object(p) obj)

Initialize the object to act as a proxy for obj.

_sprintf(int c, mapping|void params)

Special case for c == 'O', where it will return sprintf("%O(%O)", this_program, obj), and otherwise proxy the call.

void _destruct()/void destroy()

These lfuns will not be present as the act of them being proxied would likely confuse the proxied object.

The same proxy class will be returned if this function is called with the same program multiple times.

Get a list of value key names from the register.

One of the following:

A registry key.

Returns an array of value keys stored at the specified location if any. Returns UNDEFINED on missing key. Throws errors on other failures.

This function is only available on Win32 systems.

RegGetValue(), RegGetValues()

Get a single value from the register.

One of the following:

Registry key.

Value name.

Returns the value stored at the specified location in the register if any. Returns UNDEFINED on missing keys, throws errors on other failures.

This function is only available on Win32 systems.

RegGetValues(), RegGetKeyNames()

Get multiple values from the register.

One of the following:

Registry key.

Returns a mapping with all the values stored at the specified location in the register if any. Returns UNDEFINED on missing key. Throws errors on other failures.

This function is only available on Win32 systems.

RegGetValue(), RegGetKeyNames()

Don't unquote backslash-sequences in quoted strings during tokenizing. This is used for bug-compatibility with Microsoft...

tokenize(), tokenize_labled()

The undefined value; ie a zero for which zero_type() returns 1.

Perform a compile-time assertion check.

If constant_expression is false, a compiler error message containing constant_message will be generated.

Note that the function call compiles to the null statement, and thus does not affect the run-time.

cpp::static_assert

Automap execution function.

Function to call for each of the mapped arguments.

Arguments for fun. Either

This function is used by the compiler to implement the automap syntax, and should in normal circumstances never be used directly.

It may however show up during module dumping and in backtraces.

It is an error not to have any Builtin.automap_markers in args.

Builtin.automap_marker, map()

Type attribute handler for "sprintf_format".

Attribute to handle, either "sprintf_format" or "strict_sprintf_format".

Sprintf-style formatting string to generate type information from.

Declared type of the fmt argument (typically string).

Continuation function type after the fmt argument. This is scanned for the type attribute "sprintf_args" to determine where the remaining arguments to sprintf() will come from.

This function is typically called from PikeCompiler()->apply_attribute_constant() and is used to perform stricter compile-time argument checking of sprintf()-style functions.

It currently implements two operating modes depending on the value of attr:

Returns cont_type with "sprintf_args" replaced by the arguments required by the fmt formatting string, and "sprintf_result" replaced by the resulting string type.

PikeCompiler()->apply_attribute_constant(), sprintf()

Program used internally by the compiler to create objects that are later modified into instances of the compiled program by the compiler.

__placeholder_object

Object used internally by the compiler.

__null_program

These are aliases for the corresponding functions in Pike.DefaultBackend.

Pike.Backend()->call_out(), Pike.Backend()->_do_call_outs(), Pike.Backend()->find_call_out(), Pike.Backend()->remove_call_out(), Pike.Backend()->call_out_info()

This function does the same as exit, but doesn't bother to clean up the Pike interpreter before exiting. This means that no destructors will be called, caches will not be flushed, file locks might not be released, and databases might not be closed properly.

Use with extreme caution.

exit()

This function only exists so that it is possible to set a gdb breakpoint on the function pike_gdb_breakpoint.

m_delete callback.

Get a random entry.

An array ({ key, value }).

This is an object containing the classes for all static (ie non-dynamic) C-modules.

In a typic Pike with support for dynamic modules the contained module classes are:

Builtin

Gmp

_Stdio

_math

_system

If the Pike binary lacks support for dynamic modules, all C-modules will show up here.

Return the absolute value for f. If f is an object it must implement lfun::`< and unary lfun::`-.

Return the arcus cosine value for f. The result will be in radians.

cos(), asin()

Return the hyperbolic arcus cosine value for f.

cosh(), asinh()

Add a new predefined constant.

This function is often used to add builtin functions. All programs compiled after the add_constant() function has been called can access value by the name name.

If there is a constant called name already, it will be replaced by by the new definition. This will not affect already compiled programs.

Calling add_constant() without a value will remove that name from the list of constants. As with replacing, this will not affect already compiled programs.

all_constants()

Add a directory to search for include files.

This is the same as the command line option -I.

Note that the added directory will only be searched when using < > to quote the included file.

remove_include_path()

Add a directory to search for modules.

This is the same as the command line option -M.

remove_module_path()

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).

if path is a ZIP archive, this argument will determine the path within the archive to be searched.

Add a directory to search for programs.

This is the same as the command line option -P.

remove_program_path()

Construct an array with the arguments as indices.

This function could be written in Pike as:

array aggregate(mixed ... elems) { return elems; }

Arrays are dynamically allocated there is no need to declare them like int a[10]=allocate(10); (and it isn't possible either) like in C, just array(int) a=allocate(10); will do.

sizeof(), arrayp(), allocate()

Construct a mapping.

Groups the arguments together two and two in key-index pairs and creates a mapping of those pairs. Generally, the mapping literal syntax is handier: ([ key1:val1, key2:val2, ... ])

sizeof(), mappingp(), mkmapping()

Construct a multiset with the arguments as indices. The multiset will not contain any values. This method is most useful when constructing multisets with map or similar; generally, the multiset literal syntax is handier: (<elem1, elem2, ...>) With it, it's also possible to construct a multiset with values: (<index1: value1, index2: value2, ...>)

sizeof(), multisetp(), mkmultiset()

Set an alarm clock for delivery of a signal.

alarm() arranges for a SIGALRM signal to be delivered to the process in seconds seconds.

If seconds is 0 (zero), no new alarm will be scheduled.

Any previous alarms will in any case be canceled.

Returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.

This function is only available on platforms that support signals.

ualarm(), signal(), call_out()

Returns a mapping containing all global constants, indexed on the name of the constant, and with the value of the constant as value.

add_constant()

Allocate an array of size elements. If init is specified then each element is initialized by copying that value recursively.

sizeof(), aggregate(), arrayp()

This function works just like sscanf(), but returns the matched results in an array instead of assigning them to lvalues. This is often useful for user-defined sscanf strings.

sscanf(), `/()

Return the arcus sine value for f. The result will be in radians.

sin(), acos()

Return the hyperbolic arcus sine value for f.

sinh(), acosh()

Returns the arcus tangent value for f. The result will be in radians.

tan(), asin(), acos(), atan2()

Returns the arcus tangent value for f1/f2, and uses the signs of f1 and f2 to determine the quadrant. The result will be in radians.

tan(), asin(), acos(), atan()

Returns the hyperbolic arcus tangent value for f.

tanh(), asinh(), acosh()

This function puts the callback in a queue of callbacks to call when pike exits. The call order is reversed, i.e. callbacks that have been added earlier are called after callback.

Please note that atexit callbacks are not called if Pike exits abnormally.

exit(), _exit()

Replace atomically the value for a key in a mapping or array.

Mapping or array to alter.

Key or index to change the value for.

Value to change to. If value is UNDEFINED and map is a mapping this function function behaves exactly as m_delete(map, key).

Returns the previous value for key. If map is a mapping and there was no previous value UNDEFINED is returned.

If map is an object lfun::_m_replace() will be called in it.

m_delete()

Get a description of the current call stack.

A bit mask of flags affecting generation of the backtrace.

Currently a single flag is defined:

The description is returned as an array with one entry for each call frame on the stack.

The entries are represented by Pike.BacktraceFrame objects.

The current call frame will be last in the array.

Please note that the frame order may be reversed in a later version of Pike to accommodate for deferred backtraces.

Note that the arguments reported in the backtrace are the current values of the variables, and not the ones that were at call-time. This can be used to hide sensitive information from backtraces (eg passwords).

In old versions of Pike the entries used to be represented by arrays of the following format:

The above format is still supported by eg describe_backtrace().

catch(), throw()

Same as sprintf("%t",x);

sprintf()

Render the internally used binary representation of the key into a string as a strings of '0's and '1's.

Cast callback. Supports only cast to mapping and behaves as the inverse of create().

Return the closest integer value greater or equal to f.

ceil() does not return an int, merely an integer value stored in a float.

floor(), round()

Extract a column from a two-dimensional array.

This function is exactly equivalent to:

map(data, lambda(mixed x,mixed y) { return x[y]; }, index)

Except of course it is a lot shorter and faster. That is, it indices every index in the array data on the value of the argument index and returns an array with the results.

rows()

Compile a string to a program.

This function takes a piece of Pike code as a string and compiles it into a clonable program.

The optional argument handler is used to specify an alternative error handler. If it is not specified the current master object will be used.

The optional arguments major and minor are used to tell the compiler to attempt to be compatible with Pike major.minor.

Note that source must contain the complete source for a program. It is not possible to compile a single expression or statement.

Also note that compile() does not preprocess the program. To preprocess the program you can use compile_string() or call the preprocessor manually by calling cpp().

compile_string(), compile_file(), cpp(), master(), CompilationHandler, DefaultCompilerEnvironment

Compile the Pike code contained in the file filename into a program.

This function will compile the file filename to a Pike program that can later be instantiated. It is the same as doing compile_string(Stdio.read_file(filename), filename).

compile(), compile_string(), cpp()

Compile the Pike code in the string source into a program. If filename is not specified, it will default to "-".

Functionally equal to compile(cpp(source, filename)).

compile(), cpp(), compile_file()

Copy a value recursively.

If the result value is changed destructively (only possible for multisets, arrays and mappings) the copied value will not be changed.

The resulting value will always be equal to the copied (as tested with the function equal()), but they may not the the same value (as tested with `==()).

equal()

Return the cosine value for f. f should be specified in radians.

acos(), sin(), tan()

Return the hyperbolic cosine value for f.

acosh(), sinh(), tanh()

Run a string through the preprocessor.

Preprocesses the string data with Pike's builtin ANSI-C look-alike preprocessor. If the current_file argument has not been specified, it will default to "-". charset defaults to "ISO-10646".

If the second 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 recognized:

compile()

Convert the output from a previous call to time() into a readable string containing the current year, month, day and time.

Like localtime, this function might throw an error if the ctime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative timestamp.

strftime(), time(), localtime(), gmtime(), mktime()

Decode a value from the string coded_value.

This function takes a string created with encode_value() or encode_value_canonic() and converts it back to the value that was coded.

If codec is specified, it's used as the codec for the decode. If none is specified, then one is instantiated through master()->Decoder(). As a compatibility fallback, the master itself is used if it has no Decoder class.

encode_value(), encode_value_canonic()

This function makes the thread stop for s seconds.

Only signal handlers can interrupt the sleep. Other callbacks are not called during delay. Beware that this function uses busy-waiting to achieve the highest possible accuracy.

signal(), sleep()

Calculate the depth of the tree.

Return a readable message that describes where the backtrace trace was made (by backtrace).

It may also be an error object or array (typically caught by a catch), in which case the error message also is included in the description.

Pass linewidth -1 to disable wrapping of the output.

backtrace(), describe_error(), catch(), throw()

Return the error message from an error object or array (typically caught by a catch). The type of the error is checked, hence err is declared as mixed and not object|array.

If an error message couldn't be obtained, a fallback message describing the failure is returned. No errors due to incorrectness in err are thrown.

describe_backtrace(), get_backtrace

Mark an object as destructed.

Calls o->_destruct(), and then clears all variables in the object. If no argument is given, the current object is destructed.

All pointers and function pointers to this object will become zero. The destructed object will be freed from memory as soon as possible.

Returns 1 if o has an lfun::_destruct() that returned 1 and inhibited destruction.

Code a value into a string.

This function takes a value, and converts it to a string. This string can then be saved, sent to another Pike process, packed or used in any way you like. When you want your value back you simply send this string to decode_value() and it will return the value you encoded.

Almost any value can be coded, mappings, floats, arrays, circular structures etc.

If codec is specified, it's used as the codec for the encode. If none is specified, then one is instantiated through master()->Encoder(). As a compatibility fallback, the master itself is used if it has no Encoder class.

If codec->nameof(o) returns UNDEFINED for an object, val = o->encode_object(o) will be called. The returned value will be passed to o->decode_object(o, val) when the object is decoded.

When only simple types like int, floats, strings, mappings, multisets and arrays are encoded, the produced string is very portable between pike versions. It can at least be read by any later version.

The portability when objects, programs and functions are involved depends mostly on the codec. If the byte code is encoded, i.e. when Pike programs are actually dumped in full, then the string can probably only be read by the same pike version.

decode_value(), sprintf(), encode_value_canonic()

Code a value into a string on canonical form.

Takes a value and converts it to a string on canonical form, much like encode_value(). The canonical form means that if an identical value is encoded, it will produce exactly the same string again, even if it's done at a later time and/or in another Pike process. The produced string is compatible with decode_value().

Note that this function is more restrictive than encode_value() with respect to the types of values it can encode. It will throw an error if it can't encode to a canonical form.

encode_value(), decode_value()

Create an array with an enumeration, useful for initializing arrays or as first argument to map() or foreach().

The defaults are: step = 1, start = 0, operator = `+

Advanced use

The resulting array is calculated like this:

array enumerate(int n, mixed step, mixed start, function operator)
{
  array res = allocate(n);
  for (int i=0; i < n; i++)
  {
    res[i] = start;
    start = operator(start, step);
  }
  return res;
}

map(), foreach()

This function checks if the values a and b are equivalent.

If either of the values is an object the (normalized) result of calling lfun::_equal() will be returned.

Returns 1 if both values are false (zero, destructed objects, prototype functions, etc).

Returns 0 (zero) if the values have different types.

Otherwise depending on the type of the values:

copy_value(), `==()

Throws an error. A more readable version of the code throw( ({ sprintf(f, @args), backtrace() }) ).

Object recognition constants.

Object recognition constants.

This function transforms the Pike process into a process running the program specified in the argument file with the arguments args.

If the mapping env is present, it will completely replace all environment variables before the new program is executed.

This function only returns if something went wrong during exece(2), and in that case it returns 0 (zero).

The Pike driver _dies_ when this function is called. You must either use fork() or Process.create_process() if you wish to execute a program and still run the Pike runtime.

This function is not available on all platforms.

Process.create_process(), fork(), Stdio.File->pipe()

Exit the whole Pike program with the given returncode.

Using exit() with any other value than 0 (zero) indicates that something went wrong during execution. See your system manuals for more information about return codes.

The arguments after the returncode will be used for a call to werror to output a message on stderr.

_exit()

Return the natural exponential of f. log( exp( x ) ) == x as long as exp(x) doesn't overflow an int.

pow(), log()

Filters the elements in arr through fun.

arr is treated as a set of elements to be filtered, as follows:

array

multiset

string

Each element is filtered with fun. The return value is of the same type as arr and it contains the elements that fun accepted. fun is applied in order to each element, and that order is retained between the kept elements.

If fun is an array, it should have the same length as arr. In this case, the elements in arr are kept where the corresponding positions in fun are nonzero. Otherwise fun is used as described below.

mapping

The values are filtered with fun, and the index/value pairs it accepts are kept in the returned mapping.

program

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

object

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then filtered as described above.

Unless something else is mentioned above, fun is used as filter like this:

function

fun is called for each element. It gets the current element as the first argument and extra as the rest. The element is kept if it returns true, otherwise it's filtered out.

object

The object is used as a function like above, i.e. the lfun::`() method in it is called.

multiset

mapping

fun is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.

"zero or left out"

Each element that is callable is called with extra as arguments. The element is kept if the result of the call is nonzero, otherwise it's filtered out. Elements that aren't callable are also filtered out.

string

Each element is indexed with the given string. If the result of that is zero then the element is filtered out, otherwise the result is called with extra as arguments. The element is kept if the return value is nonzero, otherwise it's filtered out.

This is typically used when arr is a collection of objects, and fun is the name of some predicate function in them.

The function is never destructive on arr.

map(), foreach()

Return the closest integer value less or equal to f.

floor() does not return an int, merely an integer value stored in a float.

ceil(), round()

Fork the process in two.

Fork splits the process in two, and for the parent it returns a pid object for the child. Refer to your Unix manual for further details.

This function can cause endless bugs if used without proper care.

This function is disabled when using threads.

This function is not available on all platforms.

The most common use for fork is to start sub programs, which is better done with Process.create_process().

Process.create_process()

Force garbage collection.

Perform a quick garbage collection on just this value, which must have been made weak by set_weak_flag(). All values that only have a single reference from quick will then be freed.

When quick hasn't been specified or is UNDEFINED, this function checks all the memory for cyclic structures such as arrays containing themselves and frees them if appropriate. It also frees up destructed objects and things with only weak references.

Normally there is no need to call this function since Pike will call it by itself every now and then. (Pike will try to predict when 20% of all arrays/object/programs in memory is 'garbage' and call this routine then.)

The amount of garbage is returned. This is the number of arrays, mappings, multisets, objects and programs that had no nonweak external references during the garbage collection. It's normally the same as the number of freed things, but there might be some difference since _destruct() functions are called during freeing, which can cause more things to be freed or allocated.

Pike.gc_parameters, Debug.gc_status

Returns the currently active compilation compatibility handler, or 0 (zero) if none is active.

This function should only be used during a call of compile().

get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Returns the most recent of the currently active pike compilers, or UNDEFINED if none is active.

This function should only be used during a call of compile().

get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Returns the currently active compilation error handler (second argument to compile()), or 0 (zero) if none is active.

This function should only be used during a call of compile().

get_active_compilation_handler(), compile(), CompilationHandler

Returns an array of arrays with all groups in the system groups source. Each element in the returned array has the same structure as in getgrent function.

The groups source is system dependant. Refer to your system manuals for information about how to set the source.

getgrent()

Returns an array with all users in the system.

An array with arrays of userinfo as in getpwent.

getpwent() getpwnam() getpwuid()

Return the backtrace array from an error object or array (typically caught by a catch), or zero if there is none. Errors are thrown on if there are problems retrieving the backtrace.

describe_backtrace(), describe_error()

Gets all groups which a given user is a member of.

UID or loginname of the user

get_all_groups() getgrgid() getgrnam() getpwuid() getpwnam()

Creates and returns a canonical iterator for data.

This function is used by foreach to get an iterator for an object.

Iterator, lfun::_get_iterator

Queries the environment variables.

A cached copy of the real environment is kept to make this function quicker. If the optional flag force_update 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 putenv, typically from a C-level library.

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 '\0' characters. Variable names also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

putenv()

Query the value of a specific environment variable.

Environment variable to query.

A cached copy of the real environment is kept to make this function quicker. If the optional flag force_update 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 putenv, typically from a C-level library.

Returns the value of the environment variable varname if it exists, and 0 (zero) otherwise.

Variable names and values cannot be wide strings nor contain '\0' characters. Variable names also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

putenv()

Get the group entry for the group with the id gid using the systemfunction getgrid(3).

The id of the group

An array with the information about the group

getgrent() getgrnam()

Get the group entry for the group with the name str using the systemfunction getgrnam(3).

The name of the group

An array with the information about the group

getgrent() getgrgid()

Return the high resolution real time spent with threads disabled since the Pike interpreter was started. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.

_disable_threads(), gethrtime()

Return the high resolution real time since some arbitrary event in the past. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

It's system dependent whether or not this time is monotonic, i.e. if it's unaffected by adjustments of the calendaric clock in the system. System.REAL_TIME_IS_MONOTONIC tells what it is. Pike tries to use monotonic time for this function if it's available.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.

System.REAL_TIME_IS_MONOTONIC, System.REAL_TIME_RESOLUTION, time(), System.gettimeofday(), gethrvtime(), Pike.implicit_gc_real_time

Return the CPU time that has been consumed by this process or thread. -1 is returned if the system couldn't determine it. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The CPU time includes both user and system time, i.e. it's approximately the same thing you would get by adding together the "utime" and "stime" fields returned by System.getrusage (but perhaps with better accuracy).

It's however system dependent whether or not it's the time consumed in all threads or in the current one only; System.CPU_TIME_IS_THREAD_LOCAL tells which. If both types are available then thread local time is preferred.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.CPU_TIME_RESOLUTION.

The garbage collector might run automatically at any time. The time it takes is not included in the figure returned by this function, so that normal measurements aren't randomly clobbered by it. Explicit calls to gc are still included, though.

The special function gauge is implemented with this function.

System.CPU_TIME_IS_THREAD_LOCAL, System.CPU_TIME_RESOLUTION, gauge(), System.getrusage(), gethrtime()

Returns the process ID of this process.

System.getppid(), System.getpgrp()

Get the user entry for login str using the systemfunction getpwnam(3).

The login name of the user whos userrecord is requested.

An array with the information about the user

getpwuid() getpwent()

Get the user entry for UID uid using the systemfunction getpwuid(3).

The uid of the user whos userrecord is requested.

An array with the information about the user

getpwnam() getpwent()

Return the value of a specified attribute, or 0 if it does not exist.

Match strings against a glob pattern.

sscanf(), Regexp

Convert seconds since 00:00:00 UTC, Jan 1, 1970 into components.

This function works like localtime() but the result is not adjusted for the local time zone.

localtime(), time(), ctime(), mktime(), strptime()

Search for index in haystack.

Returns 1 if index is in the index domain of haystack, or 0 (zero) if not found.

This function is equivalent to (but sometimes faster than):

search(indices(haystack), index) != -1

A negative index in strings and arrays as recognized by the index operators `[]() and `[]=() is not considered a proper index by has_index()

has_value(), has_prefix(), has_suffix(), indices(), search(), values(), zero_type()

Returns 1 if the string s starts with prefix, returns 0 (zero) otherwise.

When s is an object, it needs to implement lfun::_sizeof() and lfun::`[].

has_suffix(), has_value(), search()

Returns 1 if the string s ends with suffix, returns 0 (zero) otherwise.

has_prefix(), has_value(), search()

Search for value in haystack.

Returns 1 if value is in the value domain of haystack, or 0 (zero) if not found.

This function is in all cases except when both arguments are strings equivalent to (but sometimes faster than):

search(values(haystack), value) != -1

If both arguments are strings, has_value() is equivalent to:

search(haystack, value) != -1

has_index(), indices(), search(), has_prefix(), has_suffix(), values(), zero_type()

Return an integer derived from the string s. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

The hash algorithm was changed in Pike 8.1. If you want a hash that is compatible with Pike 8.0 and earlier, use hash_8_0().

The hash algorithm was also changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use hash_7_4(). The difference with regards to hash_8_0() only affects wide strings.

The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use hash_7_0().

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

hash_7_0(), hash_7_4(), hash_8_0(), hash_value

Return an integer derived from the string s. The same string always hashes to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility with code written for Pike up and including version 7.0.

This function is not NUL-safe, and is byte-order dependant.

hash(), hash_7_4

Return an integer derived from the string s. The same string always hashes to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility with code written for Pike up and including version 7.4.

This function is byte-order dependant for wide strings.

hash_7_6(), hash_7_0

Return an integer derived from the string s. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

Use hash_value() for in-process hashing (eg, for implementing lfun::_hash()) or one of the cryptographic hash functions.

This function is really bad at hashing strings. Similar string often return similar hash values.

It is especially bad for url:s, paths and similarly formatted strings.

The hash algorithm was changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use hash_7_4(). The difference only affects wide strings.

The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use hash_7_0().

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

hash(), hash_7_0(), hash_7_4(), hash_value

Return a hash value for the argument. It's an integer in the native integer range.

The hash will be the same for the same value in the running process only (the memory address is typically used as the basis for the hash value).

If the value is an object with an lfun::__hash, that function is called and its result returned.

This is the hashing method used by mappings.

lfun::__hash()

Check if a path p is fully qualified (ie not relative).

Returns 1 if the path is absolute, 0 otherwise.

SQL Null marker.

Replaced by is_val_null.

Nonzero recognition constant.

Get the current index for iter.

get_iterator()

Advance iter one step.

get_iterator()

Get the current value for iter.

get_iterator()

Send a signal to another process.

Some signals and their supposed purpose:

Note that you have to use signame to translate the name of a signal to its number.

Note that the kill function is not available on platforms that do not support signals. Some platforms may also have signals not listed here.

signal(), signum(), signame(), fork()

Limits the value x so that it's between minval and maxval. If x is an object, it must implement the lfun::`< method.

max() and min()

Return an array of all extended attributes set on the file

Load a binary module.

This function loads a module written in C or some other language into Pike. The module is initialized and any programs or constants defined will immediately be available.

When a module is loaded the C function pike_module_init() will be called to initialize it. When Pike exits pike_module_exit() will be called. These two functions must be available in the module.

The current working directory is normally not searched for dynamic modules. Please use "./name.so" instead of just "name.so" to load modules from the current directory.

Convert seconds since 00:00:00 UTC, 1 Jan 1970 into components.

This function returns a mapping with the following components:

An error is thrown if the localtime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative timestamp.

Prior to Pike 7.5 the field "timezone" was sometimes not present, and was sometimes not adjusted for daylight-saving time.

Calendar, gmtime(), time(), ctime(), mktime(), strptime()

Return the natural logarithm of f. exp( log(x) ) == x for x > 0.

pow(), exp()

Convert a string or character to lower case.

Returns a copy of the string s with all upper case characters converted to lower case, or the character c converted to lower case.

Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Charset.decoder can do the initial conversion for you.

Prior to Pike 7.5 this function only accepted strings.

upper_case(), Charset.decoder

Add a member to a multiset.

m_delete()

Clear the contents of a mapping or multiset.

This function clears the content of the mapping or multiset map so that it becomes empty. This is an atomic operation.

If map is an object lfun::_m_clear() will be called in it.

m_delete()

If map is an object that implements lfun::_m_delete(), that function will be called with index as its single argument.

Otherwise if map is a mapping or multiset the entry with index index will be removed from map destructively.

If the mapping or multiset does not have an entry with index index, nothing is done.

The value that was removed will be returned, and UNDEFINED otherwise.

Note that m_delete() changes map destructively.

mappingp()

Applies fun to the elements in arr and collects the results.

arr is treated as a set of elements, as follows:

array

multiset

string

fun is applied in order to each element. The results are collected, also in order, to a value of the same type as arr, which is returned.

mapping

fun is applied to the values, and each result is assigned to the same index in a new mapping, which is returned.

program

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

object

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then handled as described above.

fun is applied in different ways depending on its type:

function

fun is called for each element. It gets the current element as the first argument and extra as the rest. The result of the call is collected.

object

fun is used as a function like above, i.e. the lfun::`() method in it is called.

array

Each element of the fun array will be called for each element of arr.

multiset

mapping

fun is indexed with each element. The result of that is collected.

"zero or left out"

Each element that is callable is called with extra as arguments. The result of the calls are collected. Elements that aren't callable gets zero as result.

string

Each element is indexed with the given string. If the result of that is zero then a zero is collected, otherwise it's called with extra as arguments and the result of that call is collected.

This is typically used when arr is a collection of objects, and fun is the name of some function in them.

The function is never destructive on arr.

filter(), enumerate(), foreach()

Return the current master object.

May return UNDEFINED if no master has been loaded yet.

replace_master()

Returns the largest value among args. Compared objects must implement the lfun::`< method.

min() and limit()

Returns the smallest value among args. Compared objects must implement the lfun::`< method.

max() and limit()

Make a mapping from two arrays.

Makes a mapping ind[x]:val[x], 0 <= x < sizeof(ind).

ind and val must have the same size.

This is the inverse operation of indices() and values().

indices(), values()

This function creates a multiset from an array.

aggregate_multiset()

This function converts information about date and time into an integer which contains the number of seconds since 00:00:00 UTC, Jan 1, 1970.

You can either call this function with a mapping containing the following elements:

Or you can just send them all on one line as the second syntax suggests.

For proper UTC calculations ensure that isdst = 0 and timezone = 0; omitting either one of these parameters will mess up the UTC calculation.

On some operating systems (notably AIX and Win32), dates before 00:00:00 UTC, Jan 1, 1970 are not supported.

On most 32-bit systems, the supported range of dates is from Dec 13, 1901 20:45:52 UTC through to Jan 19, 2038 03:14:07 UTC (inclusive).

On most 64-bit systems, the supported range of dates is expressed in 56 bits and is thus practically unlimited (at least up to 1141 milion years in the past and into the future).

time(), ctime(), localtime(), gmtime(), strftime()

Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

Get the nth entry in order.

An array ({ key, value }).

Find out if an object identifier is a variable.

This function returns 1 if var exists as a non-protected variable in o, and returns 0 (zero) otherwise.

indices(), values()

Returns 1 if arg is an object, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), functionp(), multisetp(), floatp(), intp()

Return n raised to the power of x. If both n and x are integers the result will be an integer. If n is an object its pow method will be called with x as argument.

exp(), log()

Sets the environment variable varname to value.

If value is omitted or zero, the environment variable varname is removed.

varname and value cannot be wide strings nor contain '\0' characters. varname also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

getenv()

Returns the number of arguments given when the previous function was called.

This is useful for functions that take a variable number of arguments.

call_function()

Get a random value generated by the default RandomSystem.

RandomSystem()->random(), random_string()

This function sets the initial value for the random generator.

random()

Random.Deterministic

Get a string of random characters 0..255 with the length len from the default RandomSystem.

RandomSystem()->random_string(), random()

Remove a directory to search for include files.

This function performs the reverse operation of add_include_path().

add_include_path()

Remove a directory to search for modules.

This function performs the reverse operation of add_module_path().

add_module_path()

Remove a directory to search for programs.

This function performs the reverse operation of add_program_path().

add_program_path()

Remove the specified extended attribute.

Generic replace function.

This function can do several kinds replacement operations, the different syntaxes do different things as follows:

If all the arguments are strings, a copy of s with every occurrence of from replaced with to will be returned. Special case: to will be inserted between every character in s if from is the empty string.

If the first argument is a string, and the others array(string), a string with every occurrance of from[i] in s replaced with to[i] will be returned. Instead of the arrays from and to a mapping equivalent to mkmapping(from, to) can be used.

If the first argument is an array or mapping, the values of a which are `==() with from will be replaced with to destructively. a will then be returned.

Note that replace() on arrays and mappings is a destructive operation.

Replace the master object with o.

This will let you control many aspects of how Pike works, but beware that master.pike may be required to fill certain functions, so it is usually a good idea to have your master inherit the original master and only re-define certain functions.

FIXME: Tell how to inherit the master.

master()

Reverses a string, array or int.

String to reverse.

Array to reverse.

Integer to reverse.

Object to reverse.

Optional start index of the range to reverse. Default: 0 (zero).

Optional end index of the range to reverse. Default for strings: sizeof(s)-1. Default for arrays: sizeof(a)-1. Default for integers: Pike.get_runtime_info()->int_size - 1.

Optional arguments that are to be passed to lfun::_reverse().

This function reverses a string, char by char, an array, value by value or an int, bit by bit and returns the result. It's not destructive on the input value. For objects it simply calls lfun::_reverse() in the object, and returns the result.

Reversing strings can be particularly useful for parsing difficult syntaxes which require scanning backwards.

sscanf()

Return the closest integer value to f.

round() does not return an int, merely an integer value stored in a float.

floor(), ceil()

Select a set of rows from an array.

This function is en optimized equivalent to:

map(index, lambda(mixed x) { return data[x]; })

That is, it indices data on every index in the array index and returns an array with the results.

column()

Search for needle in haystack.

Item to search in. This can be one of:

If the optional argument start is present search is started at this position. This has no effect on mappings.

If the optional argument end is present, the search will terminate at this position (exclusive) if not found earlier.

Returns the position of needle in haystack if found.

If not found the returned value depends on the type of haystack:

If start is supplied to an iterator object without an lfun::_search(), haystack will need to implement Iterator()->set_index().

For mappings and object UNDEFINED will be returned when not found. In all other cases -1 will be returned when not found.

indices(), values(), zero_type(), has_value(), has_prefix(), has_suffix()

Set the value m to use weak or normal references in its indices and/or values (whatever is applicable). state is a bitfield built by using | between the following flags:

If a flag is absent, the corresponding field will use normal references. state can also be 1 as a compatibility measure; it's treated like Pike.WEAK.

m will be returned.

Set the attribute attr to the value value.

The flags parameter can be used to refine the semantics of the operation.

Stdio.XATTR_CREATE specifies a pure create, which fails if the named attribute exists already.

Stdio.XATTR_REPLACE 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.

1 if successful, 0 otherwise, setting errno.

Check the sign of a value.

Returns -1 if value is less than zero, 1 if value is greater than zero and 0 (zero) otherwise.

abs()

Trap signals.

This function allows you to trap a signal and have a function called when the process receives a signal. Although it IS possible to trap SIGBUS, SIGSEGV etc, I advise you not to; Pike should not receive any such signals, and if it does, it is because of bugs in the Pike interpreter. And all bugs should be reported, no matter how trifle.

The callback will receive the signal number as its only argument.

See the documentation for kill() for a list of signals.

If no second argument is given, the signal handler for that signal is restored to the default handler.

If the second argument is zero, the signal will be completely ignored.

Returns the previous signal function, or 0 if none had been registered.

kill(), signame(), signum()

Returns a string describing the signal sig.

kill(), signum(), signal()

Get a signal number given a descriptive string.

This function is the inverse of signame().

signame(), kill(), signal()

Returns the sine value for f. f should be specified in radians.

asin(), cos(), tan()

Returns the hyperbolic sine value for f.

asinh(), cosh(), tanh()

Size query.

The result will be as follows:

lfun::_sizeof()

This function makes the thread stop for s seconds.

Only signal handlers can interrupt the sleep, and only when abort_on_signal is set. If more than one thread is running the signal must be sent to the sleeping thread. Other callbacks are not called during sleep.

If s is zero then this thread will yield to other threads but not sleep otherwise. Note that Pike yields internally at regular intervals so it's normally not necessary to do this.

signal(), delay()

Sort arrays destructively.

This function sorts the array index destructively. That means that the array itself is changed and returned, no copy is created.

If extra arguments are given, they are supposed to be arrays of the same size as index. Each of these arrays will be modified in the same way as index. I.e. if index 3 is moved to position 0 in index index 3 will be moved to position 0 in all the other arrays as well.

The sort order is as follows:

• Integers and floats are sorted in ascending order.

• Strings are sorted primarily on the first characters that are different, and secondarily with shorter strings before longer. Different characters are sorted in ascending order on the character value. Thus the sort order is not locale dependent.

• Arrays are sorted recursively on the first element. Empty arrays are sorted before nonempty ones.

• Multisets are sorted recursively on the first index. Empty multisets are sorted before nonempty ones.

• Objects are sorted in ascending order according to `<(), `>() and `==().

• Other types aren't reordered.

• Different types are sorted in this order: Arrays, mappings, multisets, objects, functions, programs, strings, types, integers and floats. Note however that objects can control their ordering wrt other types with `<, `> and `==, so this ordering of types only applies to objects without those functions.

The first argument is returned.

The sort is stable, i.e. elements that are compare-wise equal aren't reordered.

Array.sort_array, reverse()

Print formated output to string.

The format string is a string containing a description of how to output the data in args. This string should generally speaking have one %<modifiers><operator> format specifier (examples: %s, %0d, %-=20s) for each of the arguments.

The following modifiers are supported:

The following operators are supported:

Most modifiers and operators are combinable in any fashion, but some combinations may render strange results.

If an argument is an object that implements lfun::_sprintf(), that callback will be called with the operator as the first argument, and the current modifiers as the second. The callback is expected to return a string.

sprintf-style formatting is applied by many formatting functions, such write() and werror(). It is also possible to get sprintf-style compile-time argument checking by using the type-attributes sprintf_format or strict_sprintf_format in combination with sprintf_args.

The 'q' operator was added in Pike 7.7.

Support for specifying modifiers via a mapping was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_STAR_MAPPING__.

Support for specifying little endian byte order to 'F' was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_NEGATIVE_F__.

lfun::_sprintf(), strict_sprintf_format, sprintf_format, sprintf_args, String.__HAVE_SPRINTF_STAR_MAPPING__, String.__HAVE_SPRINTF_NEGATIVE_F__.

Type constant used for typing extra arguments that are sent to sprintf().

strict_sprintf_format, sprintf_format, sprintf()

Type constant used for typing arguments that are optionally sent to sprintf() depending on the presence of extra arguments.

strict_sprintf_format, sprintf_args, sprintf()

Type constant used for typing the return value from sprintf().

strict_sprintf_format, sprintf_format, sprintf()

Returns the square root of f, or in the integer case, the square root truncated to the closest lower integer. If the argument is an object, the lfun _sqrt in the object will be called.

pow(), log(), exp(), floor(), lfun::_sqrt

The purpose of sscanf is to match a string data against a format string and place the matching results into a list of variables. The list of lvalues are destructively modified (which is only possible because sscanf really is a special form, rather than a pike function) with the values extracted from the data according to the format specification. Only the variables up to the last matching directive of the format string are touched.

The format string may contain strings separated by special matching directives like %d, %s %c and %f. Every such directive corresponds to one of the lvalues, in the order they are listed. An lvalue is the name of a variable, a name of a local variable, an index into an array, mapping or object. It is because of these lvalues that sscanf can not be implemented as a normal function.

Whenever a percent character is found in the format string, a match is performed, according to which operator and modifiers follow it:

Similar to sprintf, you may supply modifiers between the % character and the operator, to slightly change its behaviour from the default:

Sscanf does not use backtracking. Sscanf simply looks at the format string up to the next % and tries to match that with the string. It then proceeds to look at the next part. If a part does not match, sscanf immediately returns how many % were matched. If this happens, the lvalues for % that were not matched will not be changed.

The number of directives matched in the format string. Note that a string directive (%s or %[]) counts as a match even when matching just the empty string (which either may do).

sprintf, array_sscanf

Convert the structure to a string.

%a

The abbreviated weekday name according to the current locale

%A

The full weekday name according to the current locale.

%b

The abbreviated month name according to the current locale.

%B

The full month name according to the current locale.

%c

The preferred date and time representation for the current locale.

%C

The century number (year/100) as a 2-digit integer.

%d

The day of the month as a decimal number (range 01 to 31).

%D

Equivalent to %m/%d/%y. (for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.)

%e

Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.

%E

Modifier: use alternative format, see below.

%F

Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)

%G

The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.

%g

Like %G, but without century, that is, with a 2-digit year (00-99). (TZ)

%h

Equivalent to %b.

%H

The hour as a decimal number using a 24-hour clock (range 00 to 23).

%I

The hour as a decimal number using a 12-hour clock (range 01 to 12).

%j

The day of the year as a decimal number (range 001 to 366).

%m

The month as a decimal number (range 01 to 12).

%M

The minute as a decimal number (range 00 to 59).

%n

A newline character. (SU)

%O

Modifier: use alternative format, see below. (SU)

%p

Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".

%P

Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale.

%r

The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p.

%R

The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.

%s

The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)

%S

The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)

%t

A tab character. (SU)

%T

The time in 24-hour notation (%H:%M:%S). (SU)

%u

The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. (SU)

%U

The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.

%V

The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W.

%w

The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.