17. The rest

Return an integer derived from the string s. The same string will always hash 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 reasons.

This function is byte-order dependant for wide strings.

predef::hash(), 7.0::hash()

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.

If the directive evaluates to false, the source file will be considered to have failed dependencies, and will not be found by the resolver. In practical terms the cpp() call will return zero.

#if

This define contains a unique counter (unless it has been expanded Inte.NATIVE_MAX times) represented as an integer.

This define is defined when the Pike is running on IBM OS/2.

The version of FUSE

Root handles in the Windows registry.

These constants are only available on Win32 systems.

RegGetValue(), RegGetValues(), RegGetKeyNames()

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 threw errors on missing key in Pike 7.6 and earlier (see System.RegGetKeyNames_76()).

This function is only available on Win32 systems.

RegGetValue(), RegGetValues(), System.RegGetKeyNames_76()

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 threw errors on missing keys in Pike 7.6 and earlier (see System.RegGetValue_76()).

This function is only available on Win32 systems.

RegGetValues(), RegGetKeyNames(), System.RegGetValue_76()

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 threw errors on missing key in Pike 7.6 and earlier (see System.RegGetValues_76()).

This function is only available on Win32 systems.

RegGetValue(), RegGetKeyNames(), System.RegGetValues_76()

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

This function first posts a notice to all threads that it is time to stop. It then waits until all threads actually *have* stopped, and then then returns a lock object. All other threads will be blocked from running until that object has been freed/destroyed.

It's mainly useful to do things that require a temporary uid/gid change, since on many OS the effective user and group applies to all threads.

You should make sure that the returned object is freed even if some kind of error is thrown. That means in practice that it should only have references (direct or indirect) from function local variables. Also, it shouldn't be referenced from cyclic memory structures, since those are only destructed by the periodic gc. (This advice applies to mutex locks in general, for that matter.)

gethrdtime()

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

Find the next object/array/mapping/multiset/program or string.

All objects, arrays, mappings, multisets, programs and strings are stored in linked lists inside Pike. This function returns the next item on the corresponding list. It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

next_object(), _prev()

Find the previous object/array/mapping/multiset or program.

All objects, arrays, mappings, multisets and programs are stored in linked lists inside Pike. This function returns the previous item on the corresponding list. It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

Unlike _next() this function does not work on strings.

next_object(), _next()

Return the number of references o has.

It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

Note that the number of references will always be at least one since the value is located on the stack when this function is executed.

_next(), _prev()

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 runtime type of x.

typeof()

Logical not.

Every expression with the ! operator becomes a call to this function, i.e. !a is the same as predef::`!(a).

It's also used when necessary to test truth on objects, i.e. in a statement if (o) ... where o is an object, the test becomes the equivalent of !!o so that any lfun::`!() the object might have gets called.

If arg is an object that implements lfun::`!(), that function will be called.

If arg is 0 (zero), a destructed object, or a function in a destructed object, 1 will be returned.

Otherwise 0 (zero) will be returned.

No float is considered false, not even 0.0.

`==(), `!=(), lfun::`!()

Inequality test.

Every expression with the != operator becomes a call to this function, i.e. a!=b is the same as predef::`!=(a,b).

This is the inverse of `==(); see that function for further details.

Returns 1 if the test is successful, 0 otherwise.

`==()

Modulo.

Every expression with the % operator becomes a call to this function, i.e. a%b is the same as predef::`%(a,b).

If arg1 is an object that implements lfun::`%() then that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``%() then that function will be called with arg2 as the single argument.

Otherwise the result will be as follows:

For numbers, this means that

1. a % b always has the same sign as b (typically b is positive; array size, rsa modulo, etc, and a varies a lot more than b).

2. The function f(x) = x % n behaves in a sane way; as x increases, f(x) cycles through the values 0,1, ..., n-1, 0, .... Nothing strange happens when you cross zero.

3. The % operator implements the binary "mod" operation, as defined by Donald Knuth (see the Art of Computer Programming, 1.2.4). It should be noted that Pike treats %-by-0 as an error rather than returning 0, though.

4. / and % are compatible, so that a == b*floor(a/b) + a%b for all a and b.

`/, floor()

Bitwise and/intersection.

Every expression with the & operator becomes a call to this function, i.e. a&b is the same as predef::`&(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments the result is: `&(`&(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`&(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``&(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

The function is not destructive on the arguments - the result is always a new instance.

`|(), lfun::`&(), lfun::``&()

Call a function.

Calls the function fun with the arguments specified by args.

lfun::`()()

Multiplication/repetition/implosion.

Every expression with the * operator becomes a call to this function, i.e. a*b is the same as predef::`*(a,b). Longer * expressions are normally optimized to one call, so e.g. a*b*c becomes predef::`*(a,b,c).

If there's a single argument, that argument will be returned.

If the first argument is an object that implements lfun::`*(), that function will be called with the rest of the arguments.

If there are more than two arguments, the result will be `*(`*(arg1, arg2), @extras).

If arg2 is an object that implements lfun::``*(), that function will be called with arg1 as the single argument.

Otherwise the result will be as follows:

In Pike 7.0 and earlier the multiplication order was unspecified.

`+(), `-(), `/(), lfun::`*(), lfun::``*()

Addition/concatenation.

Every expression with the + operator becomes a call to this function, i.e. a+b is the same as predef::`+(a,b). Longer + expressions are normally optimized to one call, so e.g. a+b+c becomes predef::`+(a,b,c).

If there's a single argument, that argument is returned.

If arg is an object with only one reference and an lfun::`+=(), that function is called with the rest of the arguments, and its result is returned.

Otherwise, if arg is an object with an lfun::`+(), that function is called with the rest of the arguments, and its result is returned.

Otherwise, if any of the other arguments is an object that has an lfun::``+(), the first such function is called with the arguments leading up to it, and `+() is then called recursively with the result and the rest of the arguments.

Otherwise, if arg is UNDEFINED and the other arguments are either arrays, mappings or multisets, the first argument is ignored and the remaining are added together as described below. This is useful primarily when appending to mapping values since m[x] += ({foo}) will work even if m[x] doesn't exist yet.

Otherwise the result depends on the argument types:

The function is not destructive on the arguments - the result is always a new instance.

In Pike 7.0 and earlier the addition order was unspecified.

The treatment of UNDEFINED was new in Pike 7.0.

`-(), lfun::`+(), lfun::``+()

Negation/subtraction/set difference.

Every expression with the - operator becomes a call to this function, i.e. -a is the same as predef::`-(a) and a-b is the same as predef::`-(a,b). Longer - expressions are normally optimized to one call, so e.g. a-b-c becomes predef::`-(a,b,c).

If there's a single argument, that argument is returned negated. If arg1 is an object with an lfun::`-(), that function is called without arguments, and its result is returned.

If there are more than two arguments the result is: `-(`-(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`-(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``-(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

The function is not destructive on the arguments - the result is always a new instance.

In Pike 7.0 and earlier the subtraction order was unspecified.

`+()

Arrow indexing.

Every non-lvalue expression with the -> operator becomes a call to this function. a->b is the same as predef::`^(a,"b") where "b" is the symbol b in string form.

This function behaves like `[], except that the index is passed literally as a string instead of being evaluated.

If arg is an object that implements lfun::`->(), that function will be called with index as the single argument.

Otherwise the result will be as follows:

In an expression a->b, the symbol b can be any token that matches the identifier syntax - keywords are disregarded in that context.

An arrow indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `->= instead of this function.

`[](), lfun::`->(), ::`->(), `->=

Arrow index assignment.

Every lvalue expression with the -> operator becomes a call to this function, i.e. a->b=c is the same as predef::`->=(a,"b",c) where "b" is the symbol b in string form.

This function behaves like `[]=, except that the index is passed literally as a string instead of being evaluated.

If arg is an object that implements lfun::`->=(), that function will be called with index and val as the arguments.

val will be returned.

In an expression a->b=c, the symbol b can be any token that matches the identifier syntax - keywords are disregarded in that context.

An arrow indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `-> instead of this function.

`[]=(), lfun::`->=(), `->

Division/split.

Every expression with the / operator becomes a call to this function, i.e. a/b is the same as predef::`/(a,b).

If there are more than two arguments, the result will be `/(`/(arg1, arg2), @extras).

If arg1 is an object that implements lfun::`/(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``/(), that function will be called with arg1 as the single argument.

Otherwise the result will be as follows:

Unlike in some languages, the function f(x) = x/n (x and n integers) behaves in a well-defined way and is always rounded down. When you increase x, f(x) will increase with one for each n:th increment. For all x, (x + n) / n = x/n + 1; crossing zero is not special. This also means that / and % are compatible, so that a = b*(a/b) + a%b for all a and b.

`%

Less than test.

Every expression with the < operator becomes a call to this function, i.e. a<b is the same as predef::`<(a,b).

Returns 1 if the test is successful, 0 otherwise.

`<=(), `>(), `>=()

Left shift.

Every expression with the << operator becomes a call to this function, i.e. a<<b is the same as predef::`<<(a,b).

If arg1 is an object that implements lfun::`<<(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``<<(), that function will be called with arg1 as the single argument.

Otherwise arg1 will be shifted arg2 bits left.

`>>()

Less than or equal test.

Every expression with the <= operator becomes a call to this function, i.e. a<=b is the same as predef::`<=(a,b).

Returns 1 if the test is successful, 0 otherwise.

For total orders, e.g. integers, this is the inverse of `>().

`<(), `>(), `>=()

Equality test.

Every expression with the == operator becomes a call to this function, i.e. a==b is the same as predef::`==(a,b).

If more than two arguments are given, each argument is compared with the following one as described below, and the test is successful iff all comparisons are successful.

If the first argument is an object with an lfun::`==(), that function is called with the second as argument, unless the second argument is the same as the first argument. The test is successful iff its result is nonzero (according to `!).

Otherwise, if the second argument is an object with an lfun::`==(), that function is called with the first as argument, and the test is successful iff its result is nonzero (according to `!).

Otherwise, if the arguments are of different types, the test is unsuccessful. Function pointers to programs are automatically converted to program pointers if necessary, though.

Otherwise the test depends on the type of the arguments:

Returns 1 if the test is successful, 0 otherwise.

Floats and integers are not automatically converted to test against each other, so e.g. 0==0.0 is false.

Programs are not automatically converted to types to be compared type-wise.

`!(), `!=()

Greater than test.

Every expression with the > operator becomes a call to this function, i.e. a>b is the same as predef::`>(a,b).

Returns 1 if the arguments are strictly decreasing, and 0 (zero) otherwise.

`<(), `<=(), `>=()

Greater than or equal test.

Every expression with the >= operator becomes a call to this function, i.e. a>=b is the same as predef::`>=(a,b).

Returns 1 if the test is successful, 0 otherwise.

For total orders, e.g. integers, this is the inverse of `<().

`<=(), `>(), `<()

Right shift.

Every expression with the >> operator becomes a call to this function, i.e. a>>b is the same as predef::`>>(a,b).

If arg1 is an object that implements lfun::`>>(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``>>(), that function will be called with arg1 as the single argument.

Otherwise arg1 will be shifted arg2 bits right.

`<<()

Extracts a subrange.

This is the function form of expressions with the [..] operator. arg is the thing from which the subrange is to be extracted. start is the lower bound of the subrange and end the upper bound.

start_type and end_type specifies how the start and end indices, respectively, are to be interpreted. The types are either Pike.INDEX_FROM_BEG, Pike.INDEX_FROM_END or Pike.OPEN_BOUND. In the last case, the index value is insignificant.

The relation between [..] expressions and this function is therefore as follows:

a[i..j]    <=>	`[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_BEG)
    a[i..<j]   <=>	`[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_END)
    a[i..]     <=>	`[..] (a, i, Pike.INDEX_FROM_BEG, 0, Pike.OPEN_BOUND)
    a[<i..j]   <=>	`[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_BEG)
    a[<i..<j]  <=>	`[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_END)
    a[<i..]    <=>	`[..] (a, i, Pike.INDEX_FROM_END, 0, Pike.OPEN_BOUND)
    a[..j]     <=>	`[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_BEG)
    a[..<j]    <=>	`[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_END)
    a[..]      <=>	`[..] (a, 0, Pike.OPEN_BOUND, 0, Pike.OPEN_BOUND)

The subrange is specified as follows by the two bounds:

• If the lower bound refers to an index before the lowest allowable (typically zero) then it's taken as an open bound which starts at the first index (without any error).

• Correspondingly, if the upper bound refers to an index past the last allowable then it's taken as an open bound which ends at the last index (without any error).

• If the lower bound is less than or equal to the upper bound, then the subrange is the inclusive range between them, i.e. from and including the element at the lower bound and up to and including the element at the upper bound.

• If the lower bound is greater than the upper bound then the result is an empty subrange (without any error).

The returned value depends on the type of arg:

lfun::`[..], `[]

Indexing.

This is the function form of expressions with the [] operator, i.e. a[i] is the same as predef::`[](a,i).

If arg is an object that implements lfun::`[](), that function is called with the index argument.

Otherwise, the action depends on the type of arg:

As a compatibility measure, this function also performs range operations if it's called with three arguments. In that case it becomes equivalent to:

`[..] (arg, start, Pike.INDEX_FROM_BEG, end, Pike.INDEX_FROM_BEG)

See `[..] for further details.

An indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `[]= instead of this function.

`->(), lfun::`[](), `[]=, `[..]

Index assignment.

Every lvalue expression with the [] operator becomes a call to this function, i.e. a[b]=c is the same as predef::`[]=(a,b,c).

If arg is an object that implements lfun::`[]=(), that function will be called with index and val as the arguments.

val will be returned.

An indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `[] instead of this function.

`->=(), lfun::`[]=(), `[]

Exclusive or.

Every expression with the ^ operator becomes a call to this function, i.e. a^b is the same as predef::`^(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments, the result is: `^(`^(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`^(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``^(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

The function is not destructive on the arguments - the result is always a new instance.

`&(), `|(), lfun::`^(), lfun::``^()

Bitwise or/union.

Every expression with the | operator becomes a call to this function, i.e. a|b is the same as predef::`|(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments, the result is: `|(`|(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`|(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``|(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

The function is not destructive on the arguments - the result is always a new instance.

`&(), lfun::`|(), lfun::``|()

Complement/inversion.

Every expression with the ~ operator becomes a call to this function, i.e. ~a is the same as predef::`~(a).

The result will be as follows:

`!(), lfun::`~()

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

access() checks if the calling process can access the file path. Symbolic links are dereferenced.

The mode specifies the accessibility checks to be performed, and is either not specified or empty, in which case access() just tests if the file exists, or one or more of the characters "rwx".

r, w, and x test whether the file exists and grants read, write, and execute permissions, respectively.

The check is done using the calling process's real UID and GID, rather than the effective IDs as is done when actually attempting an operation (e.g., open(2)) on the file. This allows set-user-ID programs to easily determine the invoking user's authority.

If the calling process is privileged (i.e., its real UID is zero), then an X_OK check is successful for a regular file if execute permission is enabled for any of the file owner, group, or other.

errno(), Stdio.File

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

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(), `/()

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

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

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

FIXME: This documentation is not up to date!

Get a description of the current call stack.

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

Each entry has this format:

The current call frame will be last in the array.

Please note that the frame order may be reversed in a later version (than 7.1) 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).

catch(), throw()

Returns the last segment of a path.

dirname(), explode_path()

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

sprintf()

Returns 1 if arg is a callable, 0 (zero) otherwise.

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

Change the current directory for the whole Pike process.

Returns 1 for success, 0 (zero) otherwise.

getcwd()

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

Concatenate a number of paths to a straightforward path without any "//", "/.." or "/.". If any path argument is absolute then the result is absolute and the preceding arguments are ignored. If the result is relative then it might have leading ".." components. If the last nonempty argument ends with a directory separator then the result ends with that too. If all components in a relative path disappear due to subsequent ".." components then the result is ".".

combine_path_unix() concatenates in UNIX style, which also is appropriate for e.g. URL:s ("/" separates path components and absolute paths start with "/"). combine_path_nt() concatenates according to NT filesystem conventions ("/" and "\" separates path components and there might be a drive letter in front of absolute paths). combine_path_amigaos() concatenates according to AmigaOS filesystem conventions.

combine_path() is equivalent to combine_path_unix() on UNIX-like operating systems, and equivalent to combine_path_nt() on NT-like operating systems, and equivalent to combine_path_amigaos() on AmigaOS-like operating systems.

getcwd(), Stdio.append_path()

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

This function crypts and verifies a short string (only the first 8 characters are significant).

The first syntax crypts the string password into something that is hopefully hard to decrypt.

The second syntax is used to verify typed_password against crypted_password, and returns 1 if they match, and 0 (zero) otherwise.

Note that strings containing null characters will only be processed up until the null character.

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.

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

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. If codec is the special value -1, then decoding of types, functions, programs and objects is disabled.

Decoding a coded_value that you have not generated yourself is a security risk that can lead to execution of arbitrary code, unless codec is specified as -1.

encode_value(), encode_value_canonic()

This function makes the program 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()

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->destroy(), 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 arg is a destructed object, 0 (zero) otherwise.

zero_type, undefinedp, intp

Returns all but the last segment of a path. Some example inputs and outputs:

basename(), explode_path()

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

For all types but arrays, multisets and mappings, this operation is the same as doing a == b. For arrays, mappings and multisets however, their contents are checked recursively, and if all their contents are the same and in the same place, they are considered equal.

copy_value()

This function returns the system error from the last file operation.

Note that you should normally use Stdio.File->errno() instead.

Stdio.File->errno(), strerror()

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

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

Split a path p into its components.

This function divides a path into its components. This might seem like it could be done by dividing the string on <tt>"/"</tt>, but that will not work on some operating systems. To turn the components back into a path again, use combine_path().

Stat a file.

If the argument symlink is 1 symlinks will not be followed.

If the path specified by path doesn't exist 0 (zero) will be returned.

Otherwise an object describing the properties of path will be returned.

In Pike 7.0 and earlier this function returned an array with 7 elements. The old behaviour can be simulated with the following function:

array(int) file_stat(string path, void|int(0..1) symlink)
{
  File.Stat st = predef::file_stat(path, symlink);
  if (!st) return 0;
  return (array(int))st;
}

Stdio.Stat, Stdio.File->stat()

Truncates the file file to the length specified in length.

Returns 1 if ok, 0 if failed.

Returns a mapping describing the properties of the filesystem containing the path specified by path.

If a filesystem cannot be determined 0 (zero) will be returned.

Otherwise a mapping(string:int) with the following fields will be returned:

Please note that not all members are present on all OSs.

file_stat()

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 an array with all objects that are clones of p.

Program that the objects should be a clone of.

If true, include also objects that are clones of programs that have inherited p. Note that this adds significant overhead.

This function is only intended to be used for debug purposes.

map_all_objects()

Returns 1 if arg is a float, 0 (zero) otherwise.

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

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

Return the name of the function or program f.

If f is a global function defined in the runtime 0 (zero) will be returned.

function_object()

Return the object the function f is in.

If f is a global function defined in the runtime 0 (zero) will be returned.

Zero will also be returned if f is a constant in the parent class. In that case function_program() can be used to get the parent program.

function_name(), function_program()

Return the program the function f is in.

If f is a global function defined in the runtime 0 (zero) will be returned.

function_name(), function_object()

Returns 1 if arg is a function, 0 (zero) otherwise.

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

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 destroy() 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 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()

Returns an array of all filenames in the directory dirname, or 0 (zero) if the directory does not exist. When no dirname is given, current work directory is used.

mkdir(), cd()

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

Get profiling information.

Returns an array with two elements.

This function is only available if the runtime was compiled with the option --with-profiling.

Returns the weak flag settings for m. It's a combination of Pike.WEAK_INDICES and Pike.WEAK_VALUES.

Returns the current working directory.

cd()

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.

Timestamps prior to 1970-01-01T00:00:00 (ie negative timestamps) were not supported on NT and AIX prior to Pike 9.0.

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

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