In this chapter all the control structures in Pike will be explained. Control structures are used to control the flow of the program execution. Note that functions that make the program pause and simple function calls are not qualified as control structures.

Conditions are control structures that, given a test condition selects what code to be executed. These range from the binary "execute or not" to a large table of code where the selection of which code to run is based on an input parameter.

The simplest one is called the if statement. It can be written anywhere where a statement is expected and it looks like this:

if( expression )
  statement1;
else
  statement2;

Please note that there is no semicolon after the parenthesis or after the else. Step by step, if does the following:

1. First it evaluates expression.
2. If the result was false go to point 5.
3. Execute statement1.
4. Jump to point 6.
5. Execute statement2.
6. Done.

This is actually more or less how the interpreter executes the if statement. In short, statement1 is executed if expression is true otherwise statement2 is executed. If you are not interested in having something executed if the expression is false you can drop the whole else part like this:

if( expression )
  statement1;

If on the other hand you are not interested in evaluating something if the expression is false you should use the not operator to negate the true/false value of the expression. See FIXME: chapter for more information about the not operator. It would look like this:

if( ! expression )
  statement2;

Any of the statements here and in the rest of this chapter can also be a block of statements. A block is a list of statements, separated by semicolons and enclosed by brackets. Note that you should never put a semicolon after a block of statements. The example above would look like this;

if ( ! expression )
{
  statement;
  statement;
  statement;
}

It is also possible to place several if statements in sequence, so that if the first expression is false it continues with the next one and the next one until the first true expression is found.

if ( expression1 )
  statement1;
else if ( expression2 )
  statement2;
else if ( expression3 )
  statement3;
else
  statement4;

A special case of the above example is when in every expression you compare one variable with different values. For those applications the switch statement described below can be used instead to increas performance and simplify the code.

A more sophisticated condition control structure is the switch statement. A switch lets you select one of many choices depending on the value of an expression and it can look something like this:

switch ( expression )
{
  case constant1:
    statement1;
    break;

  case constant2:
    statement2;
    break;

  case constant3 .. constant4:
    statement3;
    break;

  case constant5:
  case constant6:
    statement4;
    // Fallthrough

  default:
    statement5;
}

As you can see, a switch statement is a bit more complicated than an if statement. It is still fairly simple however. It starts by evaluating the expression it then searches all the case statements in the following block. If one is found to be equal to the value returned by the expression, Pike will continue executing the code directly following that case statement. When a break is encountered Pike will skip the rest of the code in the switch block and continue executing after the block. Note that it is not strictly necessary to have a break before the next case statement. If there is no break before the next case statement Pike will simply continue executing and execute the code after that case statement as well.

One of the case statements in the above example differs in that it is a range. In this case, any value between constant3 and constant4 will cause Pike to jump to statement3. Note that the ranges are inclusive, so the values constant3 and constant4 are also valid.

Loops are used to execute a piece of code more than once. Since this can be done in quite a few different ways there are four different loop control structures. They may all seem very similar, but using the right one at the right time makes the code a lot shorter and simpler.

While is the simplest of the loop control structures. It looks just like an if statement without the else part:

	while ( expression )
	  statement;

The difference in how it works isn't that big either, the statement is executed if the expression is true. Then the expression is evaluated again, and if it is true the statement is executed again. Then it evaluates the expression again and so forth... Here is an example of how it could be used:

int e=1;
while(e<5)
{
  show_record(e);
  e=e+1;
}

This would call show_record with the values 1, 2, 3 and 4.

For is simply an extension of while. It provides an even shorter and more compact way of writing loops. The syntax looks like this:

for ( initializer_statement ; expression ; incrementor_expression )
  statement ;

For does the following steps:

1. Executes the the initializer_statement. The initializer statement is executed only once and is most commonly used to initialize the loop variable.
2. Evaluates expression
3. If the result was false it exits the loop and continues with the program after the loop.
4. Executes statement.
5. Executes the increment_expression.
6. Starts over from 2.

This means that the example in the while section can be written like this:

for(int e=1; e<5; e=e+1)
  show_record(e);

Sometimes it is unpractical that the expression is always evaluated before the first time the loop is executed. Quite often you want to execute something, and then do it over and over until some condition is satisfied. This is exactly when you should use the do-while statement.

do
  statement;
while ( expression );

As usual, the statement can also be a block of statements, and then you do not need a semicolon after it. To clarify, this statement executes statement first, and then evaluates the expression. If the expression is true it executes the loop again. For instance, if you want to make a program that lets your modem dial your Internet provider, it could look something like this:

do {
  modem->write("ATDT441-9109\n"); // Dial 441-9109
} while(modem->gets()[..6]] != "CONNECT");

This example assumes you have written something that can communicate with the modem by using the functions write and gets.

Foreach is unique in that it does not have an explicit test expression evaluated for each iteration in the loop. Instead, foreach executes the statement once for each element in a set. Foreach has two syntaxes, the first of which look like this:

foreach ( array_expression, variable )
  statement;

We have already seen an example of foreach in the find_song function in chapter 2. What foreach does is:

1. It evaluates the array_expression which must return an array.
2. If the array is empty, exit the loop.
3. It then assigns the first element from the array to the variable.
4. Then it executes the statement.
5. If there are more elements in the array, the next one is assigned to the variable, otherwise exit the loop.
6. Go to point 4.

Foreach is not really necessary, but it is faster and clearer than doing the same thing with a for loop, as shown here:

array tmp1 = array_expression;
for ( tmp2 = 0; tmp2 < sizeof(tmp1); tmp2++ )
{
  variable = tmp1 [ tmp2 ];
  statement;
}

The second syntax for foreach is the more flexible iterator syntax, which can be used to iterate over arrays, mappings, multisets and strings as well as some objects. It also has the option of providing the index value:

foreach ( iterable_expression; optional_index_variable; optional_value_variable )
  statement;

This is approximately equivalent to:

for (Iterator iter = get_iterator(iterable_expression); iter; iter->next()) {
  optional_index_variable = iter->index();
  optional_value_variable = iter->value();
  statement;
}

See get_iterator() for further details.

The loop control structures above are enough to solve any problem, but they are not enough to provide an easy solution to all problems. One thing that is still missing is the ability to exit a loop in the middle of it. There are three ways to do this:

break exits a loop, switch, or catch statement immediately and continues executing after the loop. Break can not be used outside of one of these. It is quite useful in conjunction with while(1) to construct command parsing loops for instance:

while(1)
{
  string command=Stdio.Readline()->read("> ");
  if(command=="quit") break;
  do_command(command);
}

When you want to break out of more than the innermost loop, you can tell break what loop to break free of using lables, as in:

array arr1, arr2;
while(1)
{
  // ...
a:if(sizeof(arr1) >= sizeof(arr2))
  {
    int i = sizeof(b), j = sizeof(yb);
    while(i)
      if(b[--i] != yb[--j])
        break a;
    // the code here is only run when arr1
    // and arr2 share some common suffix
  }
  // execution continues here
}

Inside a catch block, break will terminate the block with no exception being thrown; catch will return zero, as if execution had continued to the end of the block.

Continue does almost the same thing as break, except instead of breaking out of the loop it only breaks out of the loop body. It then continues to execute the next iteration in the loop. For a while loop, this means it jumps up to the top again. For a for loop, it jumps to the incrementor expression. For a do-while loop it jumps down to the expression at the end. To continue our example above, continue can be used like this:

while(1)
{
  string command=Stdio.Readline()->read("> ");
  if(strlen(command) == 0) continue;
  if(command=="quit") break;
  do_command(command);
}

This way, do_command will never be called with an empty string as argument.

Return doesn't just exit the loop, it exits the whole function. We have seen several examples how to use it chapter 2. None of the functions in chapter two returned anything in particular however. To do that you just put the return value right after return. Of course the type of the return value must match the type in the function declaration. If your function declaration is int main() the value after return must be an int. For instance, if we wanted to make a program that always returns an error code to the system, just like the UNIX command false this is how it would be done:

#!/usr/local/bin/pike

int main()
{
  return 1;
}

This would return the error code 1 to the system when the program is run.

In this chapter we will discuss all the different ways to store data in Pike in detail. We have seen examples of many of these, but we haven't really gone into how they work. In this chapter we will also see which operators and functions work with the different types.

Types in Pike are used in two different contexts; during compile-time, and during run-time. Some types are only used during compile-time (void, mixed and all constructed types), all other types are also used during run-time. Also note the following functions and special forms:

type typeof(mixed x)

This special form returns the compile-time type for the expression x (which is not evaluated). Ie the type that the compiler believes that the expression will return if evaluated.

type _typeof(mixed x)

This function returns the run-type of the value x (which is evaluated).

There are two categories of run-time data types in Pike: basic types, and pointer types. The difference is that basic types are copied when assigned to a variable. With pointer types, merely the pointer is copied, that way you get two variables pointing to the same thing.

The basic types are int, float and string. For you who are accustomed to C or C++, it may seem odd that a string is a basic type as opposed to an array of char, but it is surprisingly easy to get used to.

Int is short for integer, or integer number. They are normally 32 bit integers, which means that they are in the range -2147483648 to 2147483647. (Note that on some machines an int might be larger than 32 bits.) If Pike is compiled with bignum support the 32 bit limitation does not apply and thus the integers can be of arbitrary size. Since they are integers, no decimals are allowed. An integer constant can be written in several ways:

All of the above represent the number 78. Octal notation means that each digit is worth 8 times as much as the one after. Hexadecimal notation means that each digit is worth 16 times as much as the one after. Hexadecimal notation uses the letters a, b, c, d, e and f to represent the numbers 10, 11, 12, 13, 14 and 15. In binary notation every digit is worth twice the value of the succeding digit, but only 1:s and 0:s are used. The ASCII notation gives the ASCII value of the character between the single quotes. In this case the character is N which just happens to be 78 in ASCII. Some characters, like special characters as newlines, can not be placed within single quotes. The special generation sequence for those characters, listed under strings, must be used instead. Specifically this applies to the single quote character itself, which has to be written as '\''.

When pike is compiled with bignum support integers in never overflow or underflow when they reach the system-defined maxint/minint. Instead they are silently converted into bignums. Integers are usually implemented as 2-complement 32-bits integers, and thus are limited within -2147483648 and 2147483647. This may however vary between platforms, especially 64-bit platforms. FIXME: Conversion back to normal integer?

All the arithmetic, bitwise and comparison operators can be used on integers. Also note these functions:

int intp(mixed x)

This function returns 1 if x is an int, 0 otherwise.

int random(int x)

This function returns a random number greater or equal to zero and smaller than x.

int reverse(int x)

This function reverses the order of the bits in x and returns the new number. It is not very useful.

int sqrt(int x)

This computes the square root of x. The value is always rounded down.

Although most programs only use integers, they are unpractical when doing trigonometric calculations, transformations or anything else where you need decimals. For this purpose you use float. Floats are normally 32 bit floating point numbers, which means that they can represent very large and very small numbers, but only with 9 accurate digits. To write a floating point constant, you just put in the decimals or write it in the exponential form:

Of course you can have any number of decimals to increase the accuracy. Usually digits after the ninth digit are ignored, but on some architectures float might have higher accuracy than that. In the exponential form, e means "times 10 to the power of", so 1.0e9 is equal to "1.0 times 10 to the power of 9". FIXME: float and int is not compatible and no implicit cast like in C++

All the arithmetic and comparison operators can be used on floats. Also, these functions operates on floats:

trigonometric functions

The trigonometric functions are: sin, asin, cos, acos, tan and atan. If you do not know what these functions do you probably don't need them. Asin, acos and atan are of course short for arc sine, arc cosine and arc tangent. On a calculator they are often known as inverse sine, inverse cosine and inverse tangent.

float log(float x)

This function computes the natural logarithm of x,

float exp(float x)

This function computes e raised to the power of x.

float pow(float|int x, float|int y)

This function computes x raised to the power of y.

float sqrt(float x)

This computes the square root of x.

float floor(float x)

This function computes the largest integer value less than or equal to x. Note that the value is returned as a float, not an int.

float ceil(float x)

This function computes the smallest integer value greater than or equal to x and returns it as a float.

float round(float x)

This function computes the closest integer value to x and returns it as a float.

A string can be seen as an array of values from 0 to 2³²-1. Usually a string contains text such as a word, a sentence, a page or even a whole book. But it can also contain parts of a binary file, compressed data or other binary data. Strings in Pike are shared, which means that identical strings share the same memory space. This reduces memory usage very much for most applications and also speeds up string comparisons. We have already seen how to write a constant string:

"hello world" // hello world
"he" "llo"    // hello
"\116"        // N (116 is the octal ASCII value for N)
"\t"          // A tab character
"\n"          // A newline character
"\r"          // A carriage return character
"\b"          // A backspace character
"\0"          // A null character
"\""          // A double quote character
"\\"          // A singe backslash
"\x4e"        // N (4e is the hexadecimal ASCII value for N)
"\d78"        // N (78 is the decimal ACII value for N)
"hello world\116\t\n\r\b\0\"\\" // All of the above
"\xff"        // the character 255
"\xffff"      // the character 65536
"\xffffff"    // the character 16777215
"\116""3"     // 'N' followed by a '3'

As you can see, any sequence of characters within double quotes is a string. The backslash character is used to escape characters that are not allowed or impossible to type. As you can see, \t is the sequence to produce a tab character, \\ is used when you want one backslash and \" is used when you want a double quote (") to be a part of the string instead of ending it. Also, \XXX where XXX is an octal number from 0 to 37777777777 or \xXX where XX is 0 to ffffffff lets you write any character you want in the string, even null characters. From version 0.6.105, you may also use \dXXX where XXX is 0 to 2³²-1. If you write two constant strings after each other, they will be concatenated into one string.

You might be surprised to see that individual characters can have values up to 2³²-1 and wonder how much memory that use. Do not worry, Pike automatically decides the proper amount of memory for a string, so all strings with character values in the range 0-255 will be stored with one byte per character. You should also beware that not all functions can handle strings which are not stored as one byte per character, so there are some limits to when this feature can be used.

Although strings are a form of arrays, they are immutable. This means that there is no way to change an individual character within a string without creating a new string. This may seem strange, but keep in mind that strings are shared, so if you would change a character in the string "foo", you would change *all* "foo" everywhere in the program.

However, the Pike compiler will allow you to to write code like you could change characters within strings, the following code is valid and works:

string s="hello torld";
s[6]='w';

However, you should be aware that this does in fact create a new string and it may need to copy the string s to do so. This means that the above operation can be quite slow for large strings. You have been warned. Most of the time, you can use replace, sscanf, `/ or some other high-level string operation to avoid having to use the above construction too much.

All the comparison operators plus the operators listed here can be used on strings:

Summation

Adding strings together will simply concatenate them. "foo"+"bar" becomes "foobar".

Subtraction

Subtracting one string from another will remove all occurrences of the second string from the first one. So "foobarfoogazonk" - "foo" results in "bargazonk".

Indexing

Indexing will let you get the ASCII value of any character in a string. The first index is zero.

Range

The range operator will let you copy any part of the string into a new string. Example: "foobar"[2..4] will return "oba".

Division

Division will let you divide a string at every occurrence of a word or character. For instance if you do "foobargazonk" / "o" the result would be ({"f","","bargaz","nk"}). It is also possible to divide the string into strings of length N by dividing the string by N. If N is converted to a float before dividing, the reminder of the division will be included in the result.

Multiplication

The inverse of the division operator can be accomplished by multiplying an array with a string. So if you evaluate ({"f","","bargaz","nk"}) * "o" the result would be "foobargazonk".

Modulo

To complement the division operator, you can do string % int. This operator will simply return the part of the string that was not included in the array returned by string / int

Also, these functions operates on strings:

string String.capitalize(string s)

Returns s with the first character converted to upper case.

int String.count(string haystack, string needle)

Returns the number of occurances of needle in haystack. Equivalent to sizeof(haystack/needle)-1.

int String.width(string s)

Returns the width s in bits (8, 16 or 32).

string lower_case(string s)

Returns s with all the upper case characters converted to lower case.

string replace(string s, string from, string to)

This function replaces all occurrences of the string from in s with to and returns the new string.

string reverse(string s)

This function returns a copy of s with the last byte from s first, the second last in second place and so on.

int search(string haystack, string needle)

This function finds the first occurrence of needle in haystack and returns where it found it.

string sizeof(string s)

Same as strlen(s), returns the length of the string.

int stringp(mixed s)

This function returns 1 if s is a string, 0 otherwise.

int strlen(string s)

Returns the length of the string s.

string upper_case(string s)

This function returns s with all lower case characters converted to upper case.

The basic types are, as the name implies, very basic. They are the foundation, most of the pointer types are merely interesting ways to store the basic types. The pointer types are array, mapping, multiset, program, object and function. They are all pointers which means that they point to something in memory. This "something" is freed when there are no more pointers to it. Assigning a variable with a value of a pointer type will not copy this "something" instead it will only generate a new reference to it. Special care sometimes has to be taken when giving one of these types as arguments to a function; the function can in fact modify the "something". If this effect is not wanted you have to explicitly copy the value. More about this will be explained later in this chapter.

Arrays are the simplest of the pointer types. An array is merely a block of memory with a fixed size containing a number of slots which can hold any type of value. These slots are called elements and are accessible through the index operator. To write a constant array you enclose the values you want in the array with ({ }) like this:

({ })      // Empty array
({ 1 })    // Array containing one element of type int
({ "" })   // Array containing a string
({ "", 1, 3.0 }) // Array of three elements, each of different type

As you can see, each element in the array can contain any type of value. Indexing and ranges on arrays works just like on strings, except with arrays you can change values inside the array with the index operator. However, there is no way to change the size of the array, so if you want to append values to the end you still have to add it to another array which creates a new array. Figure 4.1 shows how the schematics of an array. As you can see, it is a very simple memory structure.

Operators and functions usable with arrays:

indexing ( arr [ c ] )

Indexing an array retrieves or sets a given element in the array. The index c has to be an integer. To set an index, simply put the whole thing on the left side of an assignment, like this: arr [ c ] = new_value

range ( arr [ from .. to ] )

The range copies the elements from, from+1, , from+2 ... to into a new array. The new array will have the size to-from+1.

comparing (a == b and a != b)

The equal operator returns 1 if a and b are the same arrays. It is not enough that they have the same size and same data. They must be the same array. For example: ({1}) == ({1}) would return 0, while array(int) a=({1}); return a==a; would return 1. Note that you cannot use the operators >, >=, < or <= on arrays.

Summation (a + b)

As with strings, summation concatenates arrays. ({1})+({2}) returns ({1,2}).

Subtractions (a - b)

Subtracting one array from another returns a copy of a with all the elements that are also present in b removed. So ({1,3,8,3,2}) - ({3,1}) returns ({8,2}).

Intersection (a & b)

Intersection returns an array with all values that are present in both a and b. The order of the elements will be the same as the the order of the elements in a. Example: ({1,3,7,9,11,12}) & ({4,11,8,9,1}) will return: ({1,9,11}).

Union (a | b)

Union works almost as summation, but it only adds elements not already present in a. So, ({1,2,3}) | ({1,3,5}) will return ({1,2,3,5}). Note: the order of the elements in a can be changed!

Xor (a ^ b)

This is also called symmetric difference. It returns an array with all elements present in a or b but the element must NOT be present in both. Example: ({1,3,5,6}) ^ ({4,5,6,7}) will return ({1,3,4,7}).

Division (a / b)

This will split the array a into an array of arrays. If b is another array, a will be split at each occurance of that array. If b is an integer or float, a will be split between every bth element. Examples: ({1,2,3,4,5})/({2,3}) will return ({ ({1}), ({4,5}) }) and ({1,2,3,4})/2 will return ({ ({1,2}), ({3,4}) }).

Modulo (a % b)

This operation is valid only if b is an integer. It will return the part of the array that was not included by dividing a by b.

array aggregate(mixed ... elems)

This function does the same as the ({ }) operator; it creates an array from all arguments given to it. In fact, writing ({1,2,3}) is the same as writing aggregate(1,2,3).

array allocate(int size)

This function allocates a new array of size size. All the elements in the new array will be zeroes.

int arrayp(mixed a)

This function returns 1 if a is an array, 0 otherwise.

array column(array(mixed) a, mixed ind)

This function goes through the array a and indexes every element in it on ind and builds an array of the results. So if you have an array a in which each element is a also an array. This function will take a cross section, by picking out element ind from each of the arrays in a. Example: column( ({ ({1,2,3}), ({4,5,6}), ({7,8,9}) }), 2) will return ({3,6,9}).

int equal(mixed a, mixed b)

This function returns 1 if if a and b look the same. They do not have to be pointers to the same array, as long as they are the same size and contain equal data.

array filter(array a, mixed func, mixed ... args)

filter returns every element in a for which func returns true when called with that element as first argument, and args for the second, third, etc. arguments. (Both a and func can be other things; see the reference for filter for details about that.)

array map(array a, mixed func, mixed ... args)

This function works similar to filter but returns the results of the function func instead of returning the elements from a for which func returns true. (Like filter, this function accepts other things for a and func; see the reference for map.)

array replace(array a, mixed from, mixed to)

This function will create a copy of a with all elements equal to from replaced by to.

array reverse(array a)

Reverse will create a copy of a with the last element first, the last but one second, and so on.

array rows(array a, array indexes)

This function is similar to column. It indexes a with each element from indexes and returns the results in an array. For example: rows( ({"a","b","c"}), ({ 2,1,2,0}) ) will return ({"c","b","c","a"}).

int search(array haystack, mixed needle)

This function returns the index of the first occurrence of an element equal (tested with ==) to needle in the array haystack.

int sizeof(mixed arr)

This function returns the number of elements in the array arr.

array sort(array arr, array ... rest)

This function sorts arr in smaller-to-larger order. Numbers, floats and strings can be sorted. If there are any additional arguments, they will be permutated in the same manner as arr. See functions for more details.

array Array.uniq(array a)

This function returns a copy of the array a with all duplicate elements removed. Note that this function can return the elements in any order.

Mappings are are really just more generic arrays. However, they are slower and use more memory than arrays, so they cannot replace arrays completely. What makes mappings special is that they can be indexed on other things than integers. We can imagine that a mapping looks like this:

Each index-value pair is floating around freely inside the mapping. There is exactly one value for each index. We also have a (magical) lookup function. This lookup function can find any index in the mapping very quickly. Now, if the mapping is called m and we index it like this: m [ i ] the lookup function will quickly find the index i in the mapping and return the corresponding value. If the index is not found, zero is returned instead. If we on the other hand assign an index in the mapping the value will instead be overwritten with the new value. If the index is not found when assigning, a new index-value pair will be added to the mapping. Writing a constant mapping is easy:

([ ])       // Empty mapping
([ 1:2 ])   // Mapping with one index-value pair, the 1 is the index
([ "one":1, "two":2 ]) // Mapping which maps words to numbers
([ 1:({2.0}), "":([]), ]) // Mapping with lots of different types

As with arrays, mappings can contain any type. The main difference is that the index can be any type too. Also note that the index-value pairs in a mapping are not stored in a specific order. You can not refer to the fourteenth key-index pair, since there is no way of telling which one is the fourteenth. Because of this, you cannot use the range operator on mappings.

The following operators and functions are important:

indexing ( m [ ind ] )

As discussed above, indexing is used to retrieve, store and add values to the mapping.

addition, subtraction, union, intersection and xor

All these operators works exactly as on arrays, with the difference that they operate on the indices. In those cases when the value can come from either mapping, it will be taken from the right side of the operator. This makes it easier to add new values to a mapping with +=. Some examples:
([1:3, 3:1]) + ([2:5, 3:7]) returns ([1:3, 2:5, 3:7 ])
([1:3, 3:1]) - ([2:5, 3:7]) returns ([1:3])
([1:3, 3:1]) | ([2:5, 3:7]) returns ([1:3, 2:5, 3:7 ])
([1:3, 3:1]) & ([2:5, 3:7]) returns ([3:7])
([1:3, 3:1]) ^ ([2:5, 3:7]) returns ([1:3, 2:5])

same ( a == b )

Returns 1 if a is the same mapping as b, 0 otherwise.

not same ( a != b )

Returns 0 if a is the same mapping as b, 1 otherwise.

array indices(mapping m)

Indices returns an array containing all the indices in the mapping m.

mixed m_delete(mapping m, mixed ind)

This function removes the index-value pair with the index ind from the mapping m. It will return the value that was removed.

int mappingp(mixed m)

This function returns 1 if m is a mapping, 0 otherwise.

mapping mkmapping(array ind, array val)

This function constructs a mapping from the two arrays ind and val. Element 0 in ind and element 0 in val becomes one index-value pair. Element 1 in ind and element 1 in val becomes another index-value pair, and so on..

mapping replace(mapping m, mixed from, mixed to)

This function creates a copy of the mapping m with all values equal to from replaced by to.

mixed search(mapping m, mixed val)

This function returns the index of the 'first' index-value pair which has the value val.

int sizeof(mapping m)

Sizeof returns how many index-value pairs there are in the mapping.

array values(mapping m)

This function does the same as indices, but returns an array with all the values instead. If indices and values are called on the same mapping after each other, without any other mapping operations in between, the returned arrays will be in the same order. They can in turn be used as arguments to mkmapping to rebuild the mapping m again.

int zero_type(mixed t)

When indexing a mapping and the index is not found, zero is returned. However, problems can arise if you have also stored zeroes in the mapping. This function allows you to see the difference between the two cases. If zero_type(m [ ind ]) returns 1, it means that the value was not present in the mapping. If the value was present in the mapping, zero_type will return something else than 1.

A multiset is almost the same thing as a mapping. The difference is that there are no values:

Instead, the index operator will return 1 if the value was found in the multiset and 0 if it was not. When assigning an index to a multiset like this: mset[ ind ] = val the index ind will be added to the multiset mset if val is true. Otherwise ind will be removed from the multiset instead.

Writing a constant multiset is similar to writing an array:

(< >)      // Empty multiset
(< 17 >)  // Multiset with one index: 17
(< "", 1, 3.0, 1 >) // Multiset with four indices

Note that you can actually have more than one of the same index in a multiset. This is normally not used, but can be practical at times.

Normally, when we say program we mean something we can execute from a shell prompt. However, Pike has another meaning for the same word. In Pike a program is the same as a class in C++. A program holds a table of what functions and variables are defined in that program. It also holds the code itself, debug information and references to other programs in the form of inherits. A program does not hold space to store any data however. All the information in a program is gathered when a file or string is run through the Pike compiler. The variable space needed to execute the code in the program is stored in an object which is the next data type we will discuss.

Writing a program is easy, in fact, every example we have tried so far has been a program. To load such a program into memory, we can use compile_file which takes a file name, compiles the file and returns the compiled program. It could look something like this:

program p = compile_file("hello_world.pike");

You can also use the cast operator like this:

program p = (program) "hello_world";

This will also load the program hello_world.pike, the only difference is that it will cache the result so that next time you do (program)"hello_world" you will receive the _same_ program. If you call compile_file("hello_world.pike") repeatedly you will get a new program each time.

There is also a way to write programs inside programs with the help of the class keyword:

class class_name {
  inherits, variables and functions
}

The class keyword can be written as a separate entity outside of all functions, but it is also an expression which returns the program written between the brackets. The class_name is optional. If used you can later refer to that program by the name class_name. This is very similar to how classes are written in C++ and can be used in much the same way. It can also be used to create structs (or records if you program Pascal). Let's look at an example:

class record {
  string title;
  string artist;
  array(string) songs;
}

array(record) records = ({});

void add_empty_record()
{
  records+=({ record() });
}

void show_record(record rec)
{
  write("Record name: "+rec->title+"\n");
  write("Artist: "+rec->artist+"\n");
  write("Songs:\n");
  foreach(rec->songs, string song)
    write("   "+song+"\n");
}

This could be a small part of a better record register program. It is not a complete executable program in itself. In this example we create a program called record which has three identifiers. In add_empty_record a new object is created by calling record. This is called cloning and it allocates space to store the variables defined in the class record. Show_record takes one of the records created in add_empty_record and shows the contents of it. As you can see, the arrow operator is used to access the data allocated in add_empty_record. If you do not understand this section I suggest you go on and read the next section about objects and then come back and read this section again.

cloning

To create a data area for a program you need to instantiate or clone the program. This is accomplished by using a pointer to the program as if it was a function and call it. That creates a new object and calls the function create in the new object with the arguments.

compiling

All programs are generated by compiling a string. The string may of course be read from a file. For this purpose there are three functions: program compile(string p); program compile_file(string filename); program compile_string(string p, string filename); compile_file simply reads the file given as argument, compiles it and returns the resulting program. compile_string instead compiles whatever is in the string p. The second argument, filename, is only used in debug printouts when an error occurs in the newly made program. Both compile_file and compile_string call compile to actually compile the string after having called cpp on it.

casting

Another way of compiling files to program is to use the cast operator. Casting a string to the type program calls a function in the master object which will compile the program in question for you. The master also keeps the program in a cache, so if you later need the same program again it will not be re-compiled.

int programp(mixed p)

This function returns 1 if p is a program, 0 otherwise.

comparisons

As with all data types == and != can be used to see if two programs are the same or not.

The following operators and functions are important:

cloning ( p ( args ) )

Creates an object from a program. Discussed in the next section.

indexing ( p [ string ], or p -> identifier )

Retreives the value of the named constant from a program.

array(string) indices(program p)

Returns an array with the names of all non-protected constants in the program.

array(mixed) values(program p)

Returns an array with the values of all non-protected constants in the program.

Although programs are absolutely necessary for any application you might want to write, they are not enough. A program doesn't have anywhere to store data, it just merely outlines how to store data. To actually store the data you need an object. Objects are basically a chunk of memory with a reference to the program from which it was cloned. Many objects can be made from one program. The program outlines where in the object different variables are stored.

Each object has its own set of variables, and when calling a function in that object, that function will operate on those variables. If we take a look at the short example in the section about programs, we see that it would be better to write it like this:

class record {
  string title;
  string artist;
  array(string) songs;

  void show()
  {
    write("Record name: "+title+"\n");
    write("Artist: "+artist+"\n");
    write("Songs:\n");
    foreach(songs, string song)
      write("   "+song+"\n");
  }
}

array(record) records = ({});

void add_empty_record()
{
  records+=({ record() });
}

void show_record(object rec)
{
  rec->show();
}

Here we can clearly see how the function show prints the contents of the variables in that object. In essence, instead of accessing the data in the object with the -> operator, we call a function in the object and have it write the information itself. This type of programming is very flexible, since we can later change how record stores its data, but we do not have to change anything outside of the record program.

Functions and operators relevant to objects:

indexing

Objects can be indexed on strings to access identifiers. If the identifier is a variable, the value can also be set using indexing. If the identifier is a function, a pointer to that function will be returned. If the identifier is a constant, the value of that constant will be returned. Note that the -> operator is actually the same as indexing. This means that o->foo is the same as o["foo"]

cloning

As discussed in the section about programs, cloning a program is done by using a pointer to the program as a function and calling it. Whenever you clone an object, all the global variables will be initialized. After that the function create will be called with any arguments you call the program with.

void destruct(object o)

This function invalidates all references to the object o and frees all variables in that object. This function is also called when o runs out of references. If there is a function named destroy in the object, it will be called before the actual destruction of the object.

array(string) indices(object o)

This function returns a list of all identifiers in the object o.

program object_program(object o)

This function returns the program from which o was cloned.

int objectp(mixed o)

This function returns 1 if o is an object, 0 otherwise. Note that if o has been destructed, this function will return 0.

object this_object()

This function returns the object in which the interpreter is currently executing.

array values(object o)

This function returns the same as rows(o,indices(o)). That means it returns all the values of the identifiers in the object o.

comparing

As with all data types == and != can be used to check if two objects are the same or not.

When indexing an object on a string, and that string is the name of a function in the object a function is returned. Despite its name, a function is really a function pointer.

When the function pointer is called, the interpreter sets this_object() to the object in which the function is located and proceeds to execute the function it points to. Also note that function pointers can be passed around just like any other data type:

int foo() { return 1; }
function bar() { return foo; }
int gazonk() { return foo(); }
int teleledningsanka() { return bar()(); }

In this example, the function bar returns a pointer to the function foo. No indexing is necessary since the function foo is located in the same object. The function gazonk simply calls foo. However, note that the word foo in that function is an expression returning a function pointer that is then called. To further illustrate this, foo has been replaced by bar() in the function teleledningsanka.

For convenience, there is also a simple way to write a function inside another function. To do this you use the lambda keyword. The syntax is the same as for a normal function, except you write lambda instead of the function name:

lambda ( types ) { statements }

The major difference is that this is an expression that can be used inside an other function. Example:

function bar() { return lambda() { return 1; }; )

This is the same as the first two lines in the previous example, the keyword lambda allows you to write the function inside bar.

Note that unlike C++ and Java you can not use function overloading in Pike. This means that you cannot have one function called 'foo' which takes an integer argument and another function 'foo' which takes a float argument.

This is what you can do with a function pointer.

calling ( f ( mixed ... args ) )

As mentioned earlier, all function pointers can be called. In this example the function f is called with the arguments args.

string function_name(function f)

This function returns the name of the function f is pointing at.

object function_object(function f)

This function returns the object the function f is located in.

int functionp(mixed f)

This function returns 1 if f is a function, 0 otherwise. If f is located in a destructed object, 0 is returned.

function this_function()

This function returns a pointer to the function it is called from. This is normally only used with lambda functions because they do not have a name.

There are two types that are pure compile-time types:

The type void is used to indicate the absence or optionality of a value. There are two typical use cases:

As the return type of a function (eg void foo();).

This indicates that the function does not return any value.

As one of the types in a type set for a function parameter (eg int foo(int|void param)).

This indicates that the caller of the function may omit that parameter when calling the function, in which case it will default to the special value UNDEFINED.

When creating functions with optional parameters the following functions may be of interest:

int undefinedp(mixed x)

This function returns 1 if x is UNDEFINED, and 0 otherwise.

int query_num_arg()

This function returns the number of arguments that the calling function got called with.

The type mixed is used to indicate that values of any type may be passed here, and that the actual type of the values that will be used at run-time is totally unknown.

This type is typically used when implementing container classes (where the actual values won't be manipulated by the code in the class), or as a convenience fall-back when the actual compile-time type is getting too complicated.

Futhermore more specific compile-time types may be constructed by either subtyping the basic types by specifying parameters (eg function(string(7bit), int(0..): string(7bit)) instead of just plain function), or by using the type union operator (`|) to specify several alternative types (eg int|float instead of mixed). Note that the run-time type may differ from the declared compile-time type (like eg function(string, int: string(7bit)) and int(17..17) respectively).

As mentioned in the beginning of this chapter, the assignment operator (=) does not copy anything when you use it on a pointer type. Instead it just creates another reference to the memory object. In most situations this does not present a problem, and it speeds up Pike's performance. However, you must be aware of this when programming. This can be illustrated with an example:

int main(int argc, array(string) argv)
{
  array(string) tmp;
  tmp=argv;
  argv[0]="Hello world.\n";
  write(tmp[0]);
}

This program will of course write Hello world.

Sometimes you want to create a copy of a mapping, array or object. To do so you simply call copy_value with whatever you want to copy as argument. Copy_value is recursive, which means that if you have an array containing arrays, copies will be made of all those arrays.

If you don't want to copy recursively, or you know you don't have to copy recursively, you can use the plus operator instead. For instance, to create a copy of an array you simply add an empty array to it, like this: copy_of_arr = arr + ({}); If you need to copy a mapping you use an empty mapping, and for a multiset you use an empty multiset.

When declaring a variable, you also have to specify what type of variable it is. For most types, such as int and string this is very easy. But there are much more interesting ways to declare variables than that, let's look at a few examples:

int x; // x is an integer
int|string x; // x is a string or an integer
array(string) x; // x is an array of strings
array x; // x is an array of mixed
mixed x; // x can be any type
string *x; // x is an array of strings

// x is a mapping from int to string
mapping(string:int) x;

// x implements Stdio.File
Stdio.File x;

// x implements Stdio.File
object(Stdio.File) x;

// x is a function that takes two integer
// arguments and returns a string
function(int,int:string) x;

// x is a function taking any amount of
// integer arguments and returns nothing.
function(int...:void) x;

// x is ... complicated
mapping(string:function(string|int...:mapping(string:array(string)))) x;

As you can see there are some interesting ways to specify types. Here is a list of what is possible:

mixed

This means that the variable can contain any type, or the function return any value.

array( type )

This means an array of elements with the type type.

mapping( key type : value type )

This is a mapping where the keys are of type key type and the values of value type.

multiset ( type )

This means a multiset containing values of the type type.

object ( program )

This means an object which 'implements' the specified program. The program can be a class, a constant, or a string. If the program is a string it will be casted to a program first. See the documentation for inherit for more information about this casting. The compiler will assume that any function or variable accessed in this object has the same type information as that function or variable has in program.

program

This too means 'an object which implements program'. program can be a class or a constant.

function( argument types : return type )

This is a function taking the specified arguments and returning return type. The argument types is a comma separated list of types that specify the arguments. The argument list can also end with ... to signify that there can be any amount of the last type.

type1 | type2

This means either type1 or type2

void

Void can only be used in certain places, if used as return type for a function it means that the function does not return a value. If used in the argument list for a function it means that that argument can be omitted. Example: function(int|void:void) this means a function that may or may not take an integer argument and does not return a value.

Namespace ::

Description

Symbols implicitly inherited from the virtual base class.

These symbols exist mainly to simplify implementation of the corresponding lfuns.

See also

lfun::

---

Method _annotations

array _annotations(object|void context, int|void access, bool|void recursive)

Description

Called by annotations()

Parameter context

Inherit in the current object to return the annotations for. If UNDEFINED or left out, this_program::this should be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

Parameter recursive

Include nested annotations from the inherits.

Builtin function to list the annotations (if any) of the identifiers of an object. This is useful when lfun::_annotations has been overloaded.

See also

annotations(), lfun::_annotations()

---

Method _indices

array(string) _indices(object|void context, int|void access)

Parameter context

Context in the current object to start the list from. If UNDEFINED or left out, this_program::this will be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

Builtin function to list the identifiers of an object. This is useful when lfun::_indices has been overloaded.

See also

::_values(), ::_types(), ::`->()

---

Method _types

array _types(object|void context, int|void access)

Parameter context

Context in the current object to start the list from. If UNDEFINED or left out, this_program::this will be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

Builtin function to list the types of the identifiers of an object. This is useful when lfun::_types has been overloaded.

See also

::_indices(), ::_values(), ::`->()

---

Method _values

array _values(object|void context, int|void access)

Parameter context

Context in the current object to start the list from. If UNDEFINED or left out, this_program::this will be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

Builtin function to list the values of the identifiers of an object. This is useful when lfun::_values has been overloaded.

See also

::_indices(), ::_types(), ::`->()

---

Method `->

mixed `->(string index, object|void context, int|void access)

Description

Builtin arrow operator.

Parameter index

Symbol in context to access.

Parameter context

Context in the current object to start the search from. If UNDEFINED or left out, this_program::this will be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

This function indexes the current object with the string index. This is useful when the arrow operator has been overloaded.

See also

::`->=()

---

Method `->=

mixed `->=(string index, mixed value, object|void context, int|void access)

Description

Builtin atomic arrow get and set operator.

Parameter index

Symbol in context to change the value of.

Parameter value

The new value.

Parameter context

Context in the current object to start the search from. If UNDEFINED or left out, this_program::this will be used (ie start at the current context and ignore any overloaded symbols).

Parameter access

Access permission override. One of the following:

0	See only public symbols.
UNDEFINED
1	See protected symbols as well.

This function indexes the current object with the string index, and sets it to value. This is useful when the arrow set operator has been overloaded.

Returns

Returns the previous value at index index of the current object.

See also

::`->()

Namespace 7.8::

Description

Pike 7.8 compatibility.

The symbols in this namespace will appear in programs that use #pike 7.8 or lower.

---

Inherit

inherit 8.0:: :

Module Crypto

Class Crypto.DSA

Description

The Digital Signature Algorithm (aka DSS, Digital Signature Standard).

---

Method generate_key

this_program generate_key()

Description

Generates a public/private key pair. Needs the public parameters p, q and g set, either through set_public_key or generate_parameters.

---

Method generate_parameters

this_program generate_parameters(int bits)

Description

Generate key parameters using nist_primes.

---

Method get_g

Gmp.mpz|zero get_g()

Description

Returns the generator.

---

Method get_p

Gmp.mpz|zero get_p()

Description

Returns the modulo.

---

Method get_q

Gmp.mpz|zero get_q()

Description

Returns the group order.

---

Method get_x

Gmp.mpz|zero get_x()

Description

Returns the private key.

---

Method get_y

Gmp.mpz|zero get_y()

Description

Returns the public key.

---

Method hash

Gmp.mpz hash(string msg)

Description

Makes a DSA hash of the messge msg.

---

Method name

string name()

Description

Returns the string "DSA".

---

Method nist_primes

array(Gmp.mpz) nist_primes(int l)

Description

The (slow) NIST method of generating a DSA prime pair. Algorithm 4.56 of Handbook of Applied Cryptography.

---

Method public_key_equal

bool public_key_equal(.DSA dsa)

Description

Compares the public key in this object with that in the provided DSA object.

---

Method raw_sign

array(Gmp.mpz) raw_sign(Gmp.mpz h, void|Gmp.mpz k)

Description

Sign the message h. Returns the signature as two Gmp.mpz objects.

---

Method raw_verify

bool raw_verify(Gmp.mpz h, Gmp.mpz r, Gmp.mpz s)

Description

Verify the signature r,s against the message h.

---

Method set_private_key

this_program set_private_key(Gmp.mpz secret)

Description

Sets the private key in this DSA object.

---

Method set_public_key

this_program set_public_key(Gmp.mpz p_, Gmp.mpz q_, Gmp.mpz g_, Gmp.mpz y_)

Description

Sets the public key in this DSA object.

---

Method set_random

this_program set_random(function(int(0..):string) r)

Description

Sets the random function, used to generate keys and parameters, to the function r. Default is Crypto.Random.random_string.

---

Method sign_rsaref

string sign_rsaref(string msg)

Description

Make a RSA ref signature of message msg.

---

Method sign_ssl

string sign_ssl(string msg)

Description

Make an SSL signature of message msg.

---

Method verify_rsaref

bool verify_rsaref(string msg, string s)

Description

Verify a RSA ref signature s of message msg.

---

Method verify_ssl

bool verify_ssl(string msg, string s)

Description

Verify an SSL signature s of message msg.

Class Crypto.RSA

---

Method cooked_get_d

string cooked_get_d()

Description

Returns the RSA private exponent (d) as a binary string, if known.

---

Method cooked_get_e

string cooked_get_e()

Description

Returns the RSA public exponent (e) as a binary string.

---

Method cooked_get_n

string cooked_get_n()

Description

Returns the RSA modulo (n) as a binary string.

---

Method cooked_get_p

string cooked_get_p()

Description

Returns the first RSA prime (p) as a binary string, if known.

---

Method cooked_get_q

string cooked_get_q()

Description

Returns the second RSA prime (q) as a binary string, if known.

---

Method cooked_sign

string cooked_sign(string digest)

Description

Signs digest as raw_sign and returns the signature as a byte string.

---

Method create

Crypto.RSA Crypto.RSA(mapping(string:Gmp.mpz|int)|void params)

Description

Can be initialized with a mapping with the elements n, e, d, p and q.

---

Method crypt

string crypt(string s)

Description

Encrypt or decrypt depending on set mode.

See also

set_encrypt_key, set_decrypt_key

---

Method decrypt

string decrypt(string s)

Description

Decrypt a message encrypted with encrypt.

---

Method encrypt

string encrypt(string s, function(int:string)|void r)

Description

Pads the message s with rsa_pad type 2, signs it and returns the signature as a byte string.

Parameter r

Optional random function to be passed down to rsa_pad.

---

Method generate_key

this_program generate_key(int(128..) bits, function(int:string)|void r)

Description

Generate a valid RSA key pair with the size bits. A random function may be provided as arguemnt r, otherwise Crypto.Random.random_string will be used. Keys must be at least 128 bits.

---

Method get_d

Gmp.mpz get_d()

Description

Returns the RSA private exponent (d), if known.

---

Method get_e

Gmp.mpz get_e()

Description

Returns the RSA public exponent (e).

---

Method get_n

Gmp.mpz get_n()

Description

Returns the RSA modulo (n).

---

Method get_p

Gmp.mpz get_p()

Description

Returns the first RSA prime (p), if known.

---

Method get_prime

Gmp.mpz get_prime(int bits, function(int:string) r)

Description

Generate a prime with bits number of bits using random function r.

---

Method get_q

Gmp.mpz get_q()

Description

Returns the second RSA prime (q), if known.

---

Method name

string name()

Description

Returns the string "RSA".

---

Method public_key_equal

bool public_key_equal(this_program rsa)

Description

Compares the public key of this RSA object with another RSA object.

---

Method query_blocksize

int query_blocksize()

Description

Returns the crypto block size, or zero if not yet set.

---

Method raw_sign

Gmp.mpz raw_sign(string digest)

Description

Pads the digest with rsa_pad type 1 and signs it.

---

Method raw_verify

bool raw_verify(string digest, Gmp.mpz s)

Description

Verifies the digest against the signature s, assuming pad type 1.

See also

rsa_pad, raw_sign

---

Method rsa_pad

Gmp.mpz rsa_pad(string message, int(1..2) type, function(int:string)|void random)

Description

Pads the message to the current block size with method type and returns the result as an integer. This is equivalent to OS2IP(EME-PKCS1-V1_5-ENCODE(message)) in PKCS-1.

Parameter type

1	The message is padded with 0xff bytes.
2	The message is padded with random data, using the random function if provided. Otherwise Crypto.Random.random_string will be used.

---

Method rsa_size

int(0..) rsa_size()

Description

Returns the size of the key in terms of number of bits.

---

Method rsa_unpad

string rsa_unpad(Gmp.mpz block, int type)

Description

Reverse the effect of rsa_pad.

---

Method set_decrypt_key

this_program set_decrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to keyand the mod to decryption.

See also

set_encrypt_key, crypt

---

Method set_encrypt_key

this_program set_encrypt_key(array(Gmp.mpz) key)

Description

Sets the public key to key and the mode to encryption.

See also

set_decrypt_key, crypt

---

Method set_private_key

this_program set_private_key(Gmp.mpz|int priv, array(Gmp.mpz|int)|void extra)

Description

Sets the private key.

Parameter priv

The private RSA exponent, often called d.

Parameter extra

Array
Gmp.mpz|int 0	The first prime, often called p.
Gmp.mpz|int 1	The second prime, often called q.

---

Method set_public_key

this_program set_public_key(Gmp.mpz|int modulo, Gmp.mpz|int pub)

Description

Sets the public key.

Parameter modulo

The RSA modulo, often called n. This value needs to be >=12.

Parameter pub

The public RSA exponent, often called e.

---

Method sha_sign

string sha_sign(string message, mixed|void r)

FIXME

Document this function.

---

Method sha_verify

int sha_verify(string message, string signature)

FIXME

Document this function.

---

Method sign

Gmp.mpz sign(string message, Crypto.Hash h)

Description

Signs the message with a PKCS-1 signature using hash algorithm h.

---

Method verify

bool verify(string msg, Crypto.Hash h, Gmp.mpz sign)

Description

Verify PKCS-1 signature sign of message msg using hash algorithm h.

Module Filesystem

---

Method `()

function(:void) `()(void|string path)

Description

FIXME: Document this function

---

Method get_filesystem

program get_filesystem(string what)

Description

FIXME: Document this function

---

Method parse_mode

int parse_mode(int old, int|string mode)

Description

FIXME: Document this function

Class Filesystem.Base

Description

Baseclass that can be extended to create new filesystems. Is used by the Tar and System filesystem classes.

---

Method apply

int apply()

Description

FIXME: Document this function

---

Method cd

Base cd(string|void directory)

Description

Change directory within the filesystem. Returns a new filesystem object with the given directory as cwd.

---

Method chmod

void chmod(string filename, int|string mode)

Description

Change mode of a file or directory.

---

Method chown

void chown(string filename, int|object owner, int|object group)

Description

Change ownership of the file or directory

---

Method chroot

Base chroot(void|string directory)

Description

Change the root of the filesystem.

---

Method cwd

string cwd()

Description

Returns the current working directory within the filesystem.

---

Method find

array find(void|function(Stat:int) mask, mixed ... extra)

Description

FIXME: Document this function

---

Method get_dir

array(string) get_dir(void|string directory, void|string|array glob)

Description

Returns an array of all files and directories within a given directory.

Parameter directory

Directory where the search should be made within the filesystem. CWD is assumed if none (or 0) is given.

Parameter glob

Return only files and dirs matching the glob (if given).

See also

[get_stats]

---

Method get_stats

array(Stat) get_stats(void|string directory, void|string|array glob)

Description

Returns stat-objects for the files and directories matching the given glob within the given directory.

See also

[get_dir]

---

Method mkdir

int mkdir(string directory, void|int|string mode)

Description

Create a new directory

---

Method open

Stdio.File open(string filename, string mode)

Description

Open a file within the filesystem

Returns

A Stdio.File object.

---

Method rm

int rm(string filename)

Description

Remove a file from the filesystem.

---

Method stat

Stat stat(string file, int|void lstat)

Description

Return a stat-object for a file or a directory within the filesystem.

Class Filesystem.Stat

Description

Describes the stat of a file

---

Method attach_statarray

void attach_statarray(array(int) a)

Description

Fills the stat-object with data from a Stdio.File.stat() call.

---

Method cd

object cd()

Description

Change to the stated directory.

Returns

the directory if the stated object was a directory, 0 otherwise.

---

Method isblk

bool isblk()

Description

Is the file a block device?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method ischr

bool ischr()

Description

Is the file a character device?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method isdir

bool isdir()

Description

Is the file (?) a directory?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method isdoor

bool isdoor()

Description

FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method isfifo

bool isfifo()

Description

Is the file a FIFO?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method islnk

bool islnk()

Description

Is the file a link to some other file or directory?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method isreg

bool isreg()

Description

Is the file a regular file?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method issock

bool issock()

Description

Is the file a socket?

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

---

Method nice_date

string nice_date()

Description

Returns the date of the stated object as cleartext.

---

Method open

Stdio.File open(string mode)

Description

Open the stated file within the filesystem

Returns

a [Stdio.File] object

See also

[Stdio.File]

---

Method set_type

void set_type(string x)

Description

Set a type for the stat-object.

Note

This call doesnot change the filetype in the underlaying filesystem.

Parameter x

Type to set. Type is one of the following:

• fifo
• chr
• dir
• blk
• reg
• lnk
• sock
• door

See also

[isfifo], [ischr], [isdir], [isblk], [isreg], [islnk], [issock], [isdoor]

Class Filesystem.System

Description

Implements an abstraction of the normal filesystem.

---

Method create

Filesystem.System Filesystem.System(void|string directory, void|string root, void|int fast, void|Filesystem.Base parent)

Description

Instanciate a new object representing the filesystem.

Parameter directory

The directory (in the real filesystem) that should become the root of the filesystemobject.

Parameter root

Internal

Parameter fast

Internal

Parameter parent

Internal

---

Inherit Base

inherit Filesystem.Base : Base

Class Filesystem.Traversion

Description

Iterator object that traverses a directory tree and returns files as values and paths as indices. Example that uses the iterator to create a really simple sort of make:

Example

object i=Filesystem.Traversion(".");
   foreach(i; string dir; string file) {
   	if(!has_suffix(file, ".c")) continue;
     file = dir+file;
     string ofile = file;
   	ofile[-1]='o';
   	object s=file_stat(ofile);
   	if(s && i->stat()->mtime<s->mtime) continue;
   	// compile file
   }

---

Method create

Filesystem.Traversion Filesystem.Traversion(string path, void|bool symlink, void|bool ignore_errors, void|function(array:array) sort_fun)

Parameter path

The root path from which to traverse.

Parameter symlink

Don't traverse symlink directories.

Parameter ignore_errors

Ignore directories that can not be accessed.

Parameter sort_fun

Sort function to be applied to directory entries before traversing. Can also be a filter function.

---

Method progress

float progress(void|float share)

Description

Returns the current progress of the traversion as a value between 0.0 and 1.0. Note that this value isn't based on the number of files, but the directory structure.

---

Method stat

Stdio.Stat stat()

Description

Returns the stat for the current index-value-pair.

Module Filesystem.Tar

---

Method create

void Filesystem.Tarcreate(string filename, void|Filesystem.Base parent, void|object file)

Description

Filesystem which can be used to mount a Tar file.

Parameter filename

The tar file to mount.

Parameter parent

The parent filesystem. If non is given, the normal system filesystem is assumed. This allows mounting a TAR-file within a tarfile.

Parameter file

If specified, this should be an open file descriptor. This object could e.g. be a Stdio.File, Gz.File or Bz2.File object.

Class Filesystem.Tar._Tar

Description

Low-level Tar Filesystem.

---

Method extract

void extract(string src_dir, string dest_dir, void|string|function(string, Filesystem.Stat:int|string) filter, void|int flags)

Description

Extracts files from the tar file in sequential order.

Parameter src_dir

The root directory in the tar file system to extract.

Parameter dest_dir

The root directory in the real file system that will receive the contents of src_dir. It is assumed to exist and be writable.

Parameter filter

A filter for the entries under src_dir to extract. If it's a string then it's taken as a glob pattern which is matched against the path below src_dir. That path always begins with a /. For directory entries it ends with a / too, otherwise not.

If it's a function then it's called for every entry under src_dir, and those where it returns nonzero are extracted. The function receives the path part below src_dir as the first argument, which is the same as in the glob case above, and the stat struct as the second. If the function returns a string, it's taken as the path below dest_dir where this entry should be extracted (any missing directories are created automatically).

If filter is zero, then everything below src_dir is extracted.

Parameter flags

Bitfield of flags to control the extraction:

Filesystem.Tar.EXTRACT_SKIP_MODE	Don't set any permission bits from the tar records.
Filesystem.Tar.EXTRACT_SKIP_EXT_MODE	Don't set set-user-ID, set-group-ID, or sticky bits from the tar records.
Filesystem.Tar.EXTRACT_SKIP_MTIME	Don't set mtime from the tar records.
Filesystem.Tar.EXTRACT_CHOWN	Set owning user and group from the tar records.
Filesystem.Tar.EXTRACT_ERR_ON_UNKNOWN	Throw an error if an entry of an unsupported type is encountered. This is ignored otherwise.

Files and directories are supported on all platforms, and symlinks are supported whereever symlink exists. Other record types are currently not supported.

Throws

I/O errors are thrown.

Module Protocols

Module Protocols.DNS

Description

Pike 7.8 compatibility.

Some symbols in predef::Protocols.DNS that are now protected used to be visible in Pike 7.8 and earlier.

---

Inherit DNS

inherit Protocols.DNS : DNS

---

Inherit DNS

inherit predef::Protocols.DNS : DNS

Description

Based on the current Protocols.DNS.

Class Protocols.DNS.async_client

Description

Pike 7.8 compatibility version of predef::Protocols.DNS.async_client.

---

Method create

Protocols.DNS.async_client Protocols.DNS.async_client(void|string|array(string) server, void|string|array(string) domain)

Description

create() used to be visible.

See also

::create()

---

Inherit async_client

inherit DNS::async_client : async_client

Description

Based on the current Protocols.DNS.server.

Class Protocols.DNS.client

Description

Pike 7.8 compatibility version of predef::Protocols.DNS.client.

---

Method create

Protocols.DNS.client Protocols.DNS.client(void|string|array(string) server, void|int|array(string) domain)

Description

create() used to be visible.

See also

::create()

---

Inherit client

inherit DNS::client : client

Description

Based on the current Protocols.DNS.client.

Class Protocols.DNS.server

Description

Pike 7.8 compatibility version of predef::Protocols.DNS.server.

---

Method create

Protocols.DNS.server Protocols.DNS.server(int|string|void arg1, string|int ... args)

Description

create() used to be visible.

See also

::create()

---

Inherit server

inherit DNS::server : server

Description

Based on the current Protocols.DNS.server.

Module SSL

Class SSL.alert

Description

Alert packet.

---

Method create

SSL.alert SSL.alert(int level, int description, int version, string|void message, mixed|void trace)

---

Inherit packet

inherit .packet : packet

Description

Based on the base packet.

Class SSL.connection

Description

SSL packet layer.

SSL.connection inherits SSL.handshake, and in addition to the state in the handshake super class, it contains the current read and write states, packet queues. This object is responsible for receiving and sending packets, processing handshake packets, and providing a clear text packages for some application.

---

Method got_data

string|int got_data(string|int s)

Description

Main receive handler. Returns a string of received application data, or 1 if a close was received, or -1 if an error occurred.

This function is intended to be called from an i/o read callback.

---

Inherit alert

inherit ADT.Queue : alert

---

Inherit application

inherit ADT.Queue : application

---

Inherit handshake

inherit .handshake : handshake

---

Inherit urgent

inherit ADT.Queue : urgent

---

Method recv_packet

protected object recv_packet(string data)

Description

Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.

---

Method send_close

void send_close()

Description

Initiate close.

---

Method send_packet

void send_packet(object packet, int|void priority)

Description

Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.

---

Method send_streaming_data

int send_streaming_data(string data)

Description

Send an application data packet. If the data block is too large then as much as possible of the beginning of it is sent. The size of the sent data is returned.

---

Method set_alert_callback

void set_alert_callback(function(object, int|object, string:void) callback)

Description

Called with alert object, sequence number of bad packet, and raw data as arguments, if a bad packet is received.

Can be used to support a fallback redirect https->http.

---

Method to_write

string|int to_write()

Description

Extracts data from the packet queues. Returns a string of data to be written, "" if there are no pending packets, 1 of the connection is being closed politely, and -1 if the connection died unexpectedly.

This function is intended to be called from an i/o write callback.

Class SSL.context

Description

Keeps the state that is shared by all SSL-connections for one server (or one port). It includes policy configuration, a server certificate, the server's private key(s), etc. It also includes the session cache.

---

Method advertise_protocols

void advertise_protocols(string ... protos)

Description

Protocols to advertise during handshake using the next protocol negotiation extension. Currently only used together with spdy.

---

Variable advertised_protocols

array(string) SSL.context.advertised_protocols

Description

List of advertised protocols using using TLS next protocol negotiation.

---

Variable auth_level

int SSL.context.auth_level

Description

Policy for client authentication. One of SSL.Constants.AUTHLEVEL_none, SSL.Constants.AUTHLEVEL_ask and SSL.Constants.AUTHLEVEL_require.

---

Variable certificates

array(string) SSL.context.certificates

Description

The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

---

Variable client_certificate_selector

function(.context, array(int), array(string):array(string)) SSL.context.client_certificate_selector

Description

A function which will select an acceptable client certificate for presentation to a remote server. This function will receive the SSL context, an array of acceptable certificate types, and a list of DNs of acceptable certificate authorities. This function should return an array of strings containing a certificate chain, with the client certificate first, (and the root certificate last, if applicable.)

---

Variable client_certificates

array(array(string)) SSL.context.client_certificates

Description

An array of certificate chains a client may present to a server when client certificate authentication is requested.

---

Variable client_rsa

Crypto.RSA SSL.context.client_rsa

Description

The client's private key (used with client certificate authentication)

---

Variable client_server_names

array(string) SSL.context.client_server_names

Description

Host names to send to the server when using the Server Name extension.

---

Variable client_use_sni

int SSL.context.client_use_sni

Description

Should an SSL client include the Server Name extension?

If so, then client_server_names should specify the values to send.

---

Variable dh_params

.Cipher.DHParameters SSL.context.dh_params

Description

Parameters for dh keyexchange.

---

Method dhe_dss_mode

void dhe_dss_mode(int|void min_keylength)

Description

Set preferred_suites to DSS based methods.

Parameter min_keylength

Minimum acceptable key length in bits.

See also

rsa_mode(), filter_weak_suites()

---

Variable dsa

Crypto.DSA SSL.context.dsa

Description

Servers default dsa key.

Note

If SNI (Server Name Indication) is used and multiple keys are available, this key will not be used, instead the appropriate SNI key will be used (the default implementation stores these in sni_keys.

---

Method filter_weak_suites

void filter_weak_suites(int min_keylength)

Description

Filter cipher suites from preferred_suites that don't have a key with an effective length of at least min_keylength bits.

---

Method get_authorities

array(string) get_authorities()

Description

Get the list of allowed authorities. See set_authorities.

---

Method get_trusted_issuers

array(array(string)) get_trusted_issuers()

Description

Get the list of trusted issuers. See set_trusted_issuers.

---

Variable long_rsa
Variable short_rsa

Crypto.RSA SSL.context.long_rsa
Crypto.RSA SSL.context.short_rsa

Description

Temporary, non-certified, private keys, used with a server_key_exchange message. The rules are as follows:

If the long_rsa is not zero its public part will be sent. If it is zero and short_rsa is set, its public part will be sent instead. If they are both zero, no server_key_exchange message is sent.

---

Method lookup_session

.session lookup_session(string id)

Description

Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.

---

Variable max_sessions

int SSL.context.max_sessions

Description

Maximum number of sessions to keep in the cache.

---

Method new_session

.session new_session()

Description

Create a new session.

---

Variable preferred_auth_methods

array(int) SSL.context.preferred_auth_methods

Description

For client authentication. Used only if auth_level is AUTH_ask or AUTH_require.

---

Variable preferred_compressors

array(int) SSL.context.preferred_compressors

Description

Always ({ COMPRESSION_null })

---

Variable preferred_suites

array(int) SSL.context.preferred_suites

Description

Cipher suites we want to support, in order of preference, best first.

---

Method purge_session

void purge_session(.session s)

Description

Remove a session from the cache.

---

Variable random

function(int:string) SSL.context.random

Description

Used to generate random cookies for the hello-message. If we use the RSA keyexchange method, and this is a server, this random number generator is not used for generating the master_secret.

---

Method record_session

void record_session(.session s)

Description

Add a session to the cache (if caching is enabled).

---

Variable require_trust

int SSL.context.require_trust

Description

When set, require the chain to be known, even if the root is self signed.

Note that if set, and certificates are set to be verified, trusted issuers must be provided, or no connections will be accepted.

---

Variable rsa

Crypto.RSA SSL.context.rsa

Description

The server's default private key

Note

If SNI (Server Name Indication) is used and multiple keys are available, this key will not be used, instead the appropriate SNI key will be used (the default implementation stores these in sni_keys.

---

Method rsa_mode

void rsa_mode(int|void min_keylength)

Description

Set preferred_suites to RSA based methods.

Parameter min_keylength

Minimum acceptable key length in bits.

See also

dhe_dss_mode(), filter_weak_suites()

---

Variable select_server_certificate_func

function(.context, array(string):array(string)) SSL.context.select_server_certificate_func

Description

A function which will select an acceptable server certificate for presentation to a client. This function will receive the SSL context, and an array of server names, if provided by the client. This function should return an array of strings containing a certificate chain, with the client certificate first, (and the root certificate last, if applicable.)

The default implementation will select a certificate chain for a given server based on values contained in sni_certificates.

---

Variable select_server_key_func

function(.context, array(string):object) SSL.context.select_server_key_func

Description

A function which will select an acceptable server key for presentation to a client. This function will receive the SSL context, and an array of server names, if provided by the client. This function should return an object matching the certificate for the server hostname.

The default implementation will select the key for a given server based on values contained in sni_keys.

---

Variable session_lifetime

int SSL.context.session_lifetime

Description

Sessions are removed from the cache when they are older than this limit (in seconds). Sessions are also removed from the cache if a connection using the session dies unexpectedly.

---

Method set_authorities

void set_authorities(array(string) a)

Description

Array of authorities that are accepted for client certificates. The server will only accept connections from clients whose certificate is signed by one of these authorities. The string is a DER-encoded certificate, which typically must be decoded using MIME.decode_base64 or Tools.PEM.Msg first.

Note that it is presumed that the issuer will also be trusted by the server. See trusted_issuers for details on specifying trusted issuers.

If empty, the server will accept any client certificate whose issuer is trusted by the server.

---

Method set_trusted_issuers

void set_trusted_issuers(array(array(string)) i)

Description

Sets the list of trusted certificate issuers.

Parameter a

An array of certificate chains whose root is self signed (ie a root issuer), and whose final certificate is an issuer that we trust. The root of the certificate should be first certificate in the chain. The string is a DER-encoded certificate, which typically must be decoded using MIME.decode_base64 or Tools.PEM.Msg first.

If this array is left empty, and the context is set to verify certificates, a certificate chain must have a root that is self signed.

---

Variable sni_certificates

mapping(string:array(string)) SSL.context.sni_certificates

Description

A mapping containing certificate chains for use by SNI (Server Name Indication). Each entry should consist of a key indicating the server hostname and the value containing the certificate chain for that hostname.

---

Variable sni_keys

mapping(string:object) SSL.context.sni_keys

Description

A mapping containing private keys for use by SNI (Server Name Indication). Each entry should consist of a key indicating the server hostname and the value containing the private key object for that hostname.

Note

keys objects may be generated from a decoded key string using Standards.PKCS.RSA.parse_private_key().

---

Variable use_cache

int SSL.context.use_cache

Description

Non-zero to enable cahing of sessions

---

Variable verify_certificates

int SSL.context.verify_certificates

Description

Determines whether certificates presented by the peer are verified, or just accepted as being valid.

Class SSL.handshake

Description

SSL.handshake keeps the state relevant for SSL handshaking. This includes a pointer to a context object (which doesn't change), various buffers, a pointer to a session object (reuse or created as appropriate), and pending read and write states being negotiated.

Each connection will have two sets or read and write state: The current read and write states used for encryption, and pending read and write states to be taken into use when the current keyexchange handshake is finished.

---

Variable client_cert_types
Variable client_cert_distinguished_names

array(int) SSL.handshake.client_cert_types
array(string) SSL.handshake.client_cert_distinguished_names

Description

A few storage variables for client certificate handling on the client side.

---

Variable client_random
Variable server_random

string SSL.handshake.client_random
string SSL.handshake.server_random

Description

Random cookies, sent and received with the hello-messages.

---

Method create

SSL.handshake SSL.handshake(int is_server, void|SSL.context ctx, void|ProtocolVersion min_version, void|ProtocolVersion max_version)

Parameter is_server

Whether this is the server end of the connection or not.

Parameter ctx

The context for the connection.

Parameter min_version

Minimum version of SSL to support. Defaults to Constants.PROTOCOL_SSL_3_0.

Parameter max_version

Maximum version of SSL to support. Defaults to Constants.PROTOCOL_minor.

---

Method handle_handshake

int(-1..1) handle_handshake(int type, string data, string raw)

Description

Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).

This function returns 0 if hadshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.

Class SSL.packet

Description

SSL Record Layer. Handle formatting and parsing of packets.

---

Method recv

object|string recv(string data, ProtocolVersion version)

Description

Receive data read from the network.

Parameter data

Raw data from the network.

Parameter version

Minor version of the SSL 3 protocol suite to create a packet for.

Returns

Returns a string of leftover data if packet is complete, otherwise 0.

If there's an error, an alert object is returned.

---

Method send

string send()

Description

Serialize the packet for sending.

Returns

Returns the serialized packet.

Class SSL.session

Description

The most important information in a session object is a choice of encryption algorithms and a "master secret" created by keyexchange with a client. Each connection can either do a full key exchange to established a new session, or reuse a previously established session. That is why we have the session abstraction and the session cache. Each session is used by one or more connections, in sequence or simultaneously.

It is also possible to change to a new session in the middle of a connection.

---

Variable cert_data

mapping SSL.session.cert_data

Description

information about the certificate in use by the peer, such as issuing authority, and verification status.

---

Variable certificate_chain

array(string) SSL.session.certificate_chain

Description

our certificate chain

---

Variable cipher_spec

.Cipher.CipherSpec SSL.session.cipher_spec

Description

Information about the encryption method derived from the cipher_suite.

---

Variable cipher_suite

int SSL.session.cipher_suite

Description

Constant defining a choice of keyexchange, encryption and mac algorithm.

---

Variable compression_algorithm

int SSL.session.compression_algorithm

Description

Always COMPRESSION_null.

---

Variable dsa

Crypto.DSA SSL.session.dsa

Description

The server's dsa private key

---

Method generate_keys

array(string) generate_keys(string client_random, string server_random, array(int) version)

Description

Generates keys appropriate for the SSL version given in version, based on the client_random and server_random.

Returns

Array
string 0	Client write MAC secret
string 1	Server write MAC secret
string 2	Client write key
string 3	Server write key
string 4	Client write IV
string 5	Server write IV

---

Variable identity

string SSL.session.identity

Description

Identifies the session to the server

---

Variable ke_method

int SSL.session.ke_method

Description

Key exchange method, also derived from the cipher_suite.

---

Variable master_secret

string SSL.session.master_secret

Description

48 byte secret shared between the client and the server. Used for deriving the actual keys.

---

Method new_client_states

array(.state) new_client_states(string client_random, string server_random, array(int) version)

Description

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

Returns

Array
SSL.state read_state	Read state
SSL.state write_state	Write state

---

Method new_server_states

array(.state) new_server_states(string client_random, string server_random, array(int) version)

Description

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

Returns

Array
SSL.state read_state	Read state
SSL.state write_state	Write state

---

Variable peer_certificate_chain

array(string) SSL.session.peer_certificate_chain

Description

the peer certificate chain

---

Variable rsa

Crypto.RSA SSL.session.rsa

Description

The server's private key

---

Method set_cipher_suite

void set_cipher_suite(int suite, ProtocolVersion|int version)

Description

Sets the proper authentication method and cipher specification for the given cipher suite and verison.

---

Method set_compression_method

void set_compression_method(int compr)

Description

Sets the compression method. Currently only COMPRESSION_null is supported.

Class SSL.sslfile

Description

Interface similar to Stdio.File.

• Handles blocking and nonblocking mode.

• Handles callback mode in an arbitrary backend (also in blocking mode).

• Read and write operations might each do both reading and writing. In callback mode that means that installing either a read or a write callback might install both internally. It also means that reading in one thread while writing in another doesn't work.

• Callback changing operations like set_blocking and set_nonblocking aren't atomic.

• Apart from the above, thread safety/atomicity characteristics are retained.

• Blocking characterstics are retained for all functions.

• is_open, connection init (create) and close (close) can do both reading and writing.

• destroy attempts to close the stream properly by sending the close packet, but since it can't do blocking I/O it's not certain that it will succeed. The stream should therefore always be closed with an explicit close call.

• Abrupt remote close without the proper handshake gets the errno System.EPIPE.

• Objects do not contain cyclic references, so they are closed and destructed timely when dropped.

---

Method close

int close(void|string how, void|int clean_close, void|int dont_throw)

Description

Close the connection. Both the read and write ends are always closed

Parameter how

This argument is only for Stdio.File compatibility and must be either "rw" or 0.

Parameter clean_close

If set then close messages are exchanged to shut down the SSL connection but not the underlying stream. It may then continue to be used for other communication afterwards. The default is to send a close message and then close the stream without waiting for a response.

Parameter dont_throw

I/O errors are normally thrown, but that can be turned off with dont_throw. In that case errno is set instead and 0 is returned. 1 is always returned otherwise. It's not an error to close an already closed connection.

Note

If a clean close is requested in nonblocking mode then the stream is most likely not closed right away, and the backend is then still needed for a while afterwards to exchange the close packets. is_open returns 2 in that time window.

Note

I/O errors from both reading and writing might occur in blocking mode.

Note

If a clean close is requested and data following the close message is received at the same time, then this object will read it and has no way to undo that. That data can be retrieved with read afterwards.

See also

shutdown

---

Method create

SSL.sslfile SSL.sslfile(Stdio.File stream, SSL.context ctx, int|void is_client, int|void is_blocking, SSL.Constants.ProtocolVersion|void min_version, SSL.Constants.ProtocolVersion|void max_version)

Description

Create an SSL connection over an open stream.

Parameter stream

Open socket or pipe to create the connection over.

Parameter ctx

The SSL context.

Parameter is_client

If is set then a client-side connection is started, server-side otherwise.

Parameter is_blocking

If is set then the stream is initially set in blocking mode, nonblocking mode otherwise.

Parameter min_version

The minimum minor version of SSL to support. Defaults to PROTOCOL_SSL_3_0.

Parameter max_version

The maximum minor version of SSL to support. Defaults to PROTOCOL_minor.

The backend used by stream is taken over and restored after the connection is closed (see close and shutdown). The callbacks and id in stream are overwritten.

Throws

Throws errors on handshake failure in blocking client mode.

---

Method destroy

protected void destroy()

Description

Try to close down the connection properly since it's customary to close files just by dropping them. No guarantee can be made that the close packet gets sent successfully though, because we can't risk blocking I/O here. You should call close explicitly.

See also

close

---

Method errno

int errno()

Returns

Returns the current error number for the connection. Notable values are:

0	No error
System.EPIPE	Connection closed by other end.

---

Method get_peer_certificate_info

mapping get_peer_certificate_info()

Returns

Returns peer certificate information, if any.

---

Method get_peer_certificates

array get_peer_certificates()

Returns

Returns the peer certificate chain, if any.

---

Method is_open

int is_open()

Returns

Returns nonzero if the stream currently is open, zero otherwise.

This function does nonblocking I/O to check for a close packet in the input buffer.

If a clean close has been requested in nonblocking mode, then 2 is returned until the close packet exchanged has been completed.

Note

In Pike 7.8 and earlier, this function returned zero in the case above where it now returns 2.

---

Method linger

bool linger(int(-1..65535)|void seconds)

Description

Set the linger time on close().

---

Variable next_protocol

string SSL.sslfile.next_protocol

Description

The next protocol chosen by the client during next protocol negotiation.

Note

Read only

---

Method query_accept_callback

function(void|object, void|mixed:int) query_accept_callback()

Returns

Returns the current accept callback.

See also

set_accept_callback

---

Method query_address

string query_address(int|void arg)

Returns

Returns the address and port of the connection.

See Stdio.File.query_address for details.

See also

Stdio.File.query_address

---

Method query_alert_callback

function(object, int|object, string:void) query_alert_callback()

Returns

Returns the current alert callback.

See also

set_alert_callback

---

Method query_backend

Pike.Backend query_backend()

Description

Return the backend used for the file callbacks.

See also

set_backend

---

Method query_callbacks

array(function(mixed, void|string:int)) query_callbacks()

Returns

Returns the currently set callbacks in the same order as the arguments to set_callbacks.

See also

set_callbacks, set_nonblocking

---

Method query_close_callback

function(void|mixed:int) query_close_callback()

Returns

Returns the current close callback.

See also

set_close_callback, set_nonblocking, query_callbacks

---

Method query_connection

SSL.connection query_connection()

Description

Return the SSL connection object.

This returns the low-level SSL.connection object.

---

Method query_context

SSL.context query_context()

Description

Return the SSL context object.

---

Method query_id

mixed query_id()

Returns

Returns the currently set id.

See also

set_id

---

Method query_read_callback

function(void|mixed, void|string:int) query_read_callback()

Returns

Returns the current read callback.

See also

set_read_callback, set_nonblocking, query_callbacks

---

Method query_stream

Stdio.File query_stream()

Description

Return the underlying stream.

Note

Avoid any temptation to do destruct(sslfile_obj->query_stream()). That almost certainly creates more problems than it solves.

You probably want to use shutdown.

See also

shutdown

---

Method query_write_callback

function(void|mixed:int) query_write_callback()

Returns

Returns the current write callback.

See also

set_write_callback, set_nonblocking, query_callbacks

---

Method read

string read(void|int length, void|bool not_all)

Description

Read some (decrypted) data from the connection. Works like Stdio.File.read.

Note

I/O errors from both reading and writing might occur in blocking mode.

See also

write

---

Method renegotiate

int renegotiate()

Description

Renegotiate the connection by starting a new handshake. Note that the accept callback will be called again when the handshake is finished.

Returns zero if there are any I/O errors. errno() will give the details.

Note

The read buffer is not cleared - a read() afterwards will return data from both before and after the renegotiation.

Bugs

Data in the write queue in nonblocking mode is not properly written before resetting the connection. Do a blocking write("") first to avoid problems with that.

---

Method set_accept_callback

void set_accept_callback(function(void|object, void|mixed:int) accept)

Description

Install a function that will be called when the handshake is finished and the connection is ready for use.

The callback function will be called with the sslfile object and the additional id arguments (set with set_id).

Note

Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.

See also

set_nonblocking, set_callbacks, query_accept_callback, query_callbacks

---

Method set_alert_callback

void set_alert_callback(function(object, int|object, string:void) alert)

Description

Install a function that will be called when an alert packet is about to be sent. It doesn't affect the callback mode - it's called both from backends and from within normal function calls like read and write.

This callback can be used to implement fallback to other protocols when used on the server side together with shutdown().

Note

This object is part of a cyclic reference whenever this is set, just like setting any other callback.

Note

This callback is not cleared by set_blocking, or settable by set_callbacks or set_nonblocking. It is also not part of the set returned by query_callbacks.

See also

query_alert_callback

---

Method set_backend

void set_backend(Pike.Backend backend)

Description

Set the backend used for the file callbacks.

See also

query_backend

---

Method set_blocking

void set_blocking()

Description

Set the stream in blocking mode. All but the alert callback are zapped.

Note

There might be some data still waiting to be written to the stream. That will be written in the next blocking call, regardless what it is.

Note

This function doesn't solve the case when the connection is used nonblocking in some backend thread and another thread switches it to blocking and starts using it. To solve that, put a call out in the backend from the other thread that switches it to blocking, and then wait until that call out has run.

Note

Prior to version 7.5.12, this function didn't clear the accept callback.

See also

set_nonblocking, set_blocking_keep_callbacks, set_nonblocking_keep_callbacks

---

Method set_blocking_keep_callbacks

void set_blocking_keep_callbacks()

Description

Set blocking mode like set_blocking, but don't alter any callbacks.

See also

set_blocking, set_nonblocking

---

Method set_callbacks

void set_callbacks(void|function(mixed, string:int) read, void|function(mixed:int) write, void|function(mixed:int) close, void|function(mixed, string:int) read_oob, void|function(mixed:int) write_oob, void|function(void|mixed:int) accept)

Description

Installs all the specified callbacks at once. Use UNDEFINED to keep the current setting for a callback.

Like set_nonblocking, the callbacks are installed atomically. As opposed to set_nonblocking, this function does not do anything with the stream, and it doesn't even have to be open.

Bugs

read_oob and write_oob are currently ignored.

See also

set_read_callback, set_write_callback, set_close_callback, set_accept_callback, query_callbacks

---

Method set_close_callback

void set_close_callback(function(void|mixed:int) close)

Description

Install a function to be called when the connection is closed, either normally or due to an error (use errno to retrieve it).

See also

query_close_callback, set_nonblocking, query_callbacks

---

Method set_id

void set_id(mixed id)

Description

Set the value to be sent as the first argument to the callbacks installed by set_callbacks.

See also

query_id

---

Method set_nonblocking

void set_nonblocking(void|function(void|mixed, void|string:int) read, void|function(void|mixed:int) write, void|function(void|mixed:int) close, void|function(void|mixed:int) read_oob, void|function(void|mixed:int) write_oob, void|function(void|mixed:int) accept)

Description

Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.

Note

Prior to version 7.5.12, this function didn't set the accept callback.

Bugs

read_oob and write_oob are currently ignored.

See also

set_callbacks, query_callbacks, set_nonblocking_keep_callbacks, set_blocking

---

Method set_nonblocking_keep_callbacks

void set_nonblocking_keep_callbacks()

Description

Set nonblocking mode like set_nonblocking, but don't alter any callbacks.

See also

set_nonblocking, set_blocking, set_blocking_keep_callbacks

---

Method set_read_callback

void set_read_callback(function(void|mixed, void|string:int) read)

Description

Install a function to be called when data is available.

See also

query_read_callback, set_nonblocking, query_callbacks

---

Method set_write_callback

void set_write_callback(function(void|mixed:int) write)

Description

Install a function to be called when data can be written.

See also

query_write_callback, set_nonblocking, query_callbacks

---

Method shutdown

Stdio.File shutdown()

Description

Shut down the SSL connection without sending any more packets.

If the connection is open then the underlying (still open) stream is returned.

If a nonclean (i.e. normal) close has been requested then the underlying stream is closed now if it wasn't closed already, and zero is returned.

If a clean close has been requested (see the second argument to close) then the behavior depends on the state of the close packet exchange: The first shutdown call after a successful exchange returns the (still open) underlying stream, and later calls return zero and clears errno. If the exchange hasn't finished then the stream is closed, zero is returned, and errno will return System.EPIPE.

See also

close, set_alert_callback

---

Method write

int write(string|array(string) data, mixed ... args)

Description

Write some (unencrypted) data to the connection. Works like Stdio.File.write except that this function often buffers some data internally, so there's no guarantee that all the consumed data has been successfully written to the stream in nonblocking mode. It keeps the internal buffering to a minimum, however.

Note

This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.

Note

I/O errors from both reading and writing might occur in blocking mode.

See also

read

Class SSL.sslport

Description

Interface similar to Stdio.Port.

---

Method accept

SSL.sslfile accept()

Description

Get the next pending SSL.sslfile from the accept_queue.

Returns

Returns the next pending SSL.sslfile if any, and 0 (zero) if there are none.

---

Variable accept_callback

function(object, mixed|void:void) SSL.sslport.accept_callback

---

Method bind

int bind(int port, function(SSL.sslfile|void, mixed|void:int) callback, string|void ip)

Description

Bind an SSL port.

Parameter port

Port number to bind.

Parameter callback

Callback to call when the SSL connection has been negotiated.

The callback is called with an SSL.sslfile as the first argument, and the id for the SSL.sslfile as the second.

If the callback is 0 (zero), then negotiated SSL.sslfiles will be enqueued for later retrieval with accept().

Parameter ip

Optional IP-number to bind.

Returns

Returns 1 if binding of the port succeeded, and 0 (zero) on failure.

See also

Stdio.Port()->bind(), SSL.sslfile()->set_accept_callback(), listen_fd()

---

Method create

SSL.sslport SSL.sslport()

Description

Create a new port for accepting SSL connections.

See also

bind(), listen_fd()

---

Method finished_callback

void finished_callback(SSL.sslfile f, mixed|void id)

Description

SSL connection accept callback.

Parameter f

The SSL.sslfile that just finished negotiation.

This function is installed as the SSL.sslfile accept callback by ssl_callback(), and enqueues the newly negotiated SSL.sslfile on the accept_queue.

If there has been an accept_callback installed by bind() or listen_fd(), it will be called with all pending SSL.sslfiles on the accept_queue.

If there's no accept_callback, then the SSL.sslfile will have to be retrieved from the queue by calling accept().

---

Inherit accept_queue

inherit ADT.Queue : accept_queue

---

Inherit context

inherit .context : context

---

Inherit socket

inherit Stdio.Port : socket

---

Method listen_fd

int listen_fd(int fd, function(SSL.sslfile|void, mixed|void:int) callback)

Description

Set up listening for SSL connections on an already opened fd.

Parameter fd

File descriptor to listen on.

Parameter callback

Callback to call when the SSL connection has been negotiated.

The callback is called with an SSL.sslfile as the first argument, and the id for the SSL.sslfile as the second.

If the callback is 0 (zero), then negotiated SSL.sslfiles will be enqueued for later retrieval with accept().

Returns

Returns 1 if listening on the fd succeeded, and 0 (zero) on failure.

See also

Stdio.Port()->listen_fd(), SSL.sslfile()->set_accept_callback(), bind()

---

Method socket_accept

Stdio.File socket_accept()

Description

Low-level accept.

See also

Stdio.Port()->accept()

---

Method ssl_callback

void ssl_callback(mixed id)

Description

Connection accept callback.

This function is installed as the Stdio.Port callback, and accepts the connection and creates a corresponding SSL.sslfile with finished_callback() as the accept callback.

See also

bind(), finished_callback()

Class SSL.state

Description

A connection switches from one set of state objects to another, one or more times during its lifetime. Each state object handles a one-way stream of packets, and operates in either decryption or encryption mode.

---

Constant Alert

constant SSL.state.Alert

---

Variable crypt

.Cipher.CipherAlgorithm SSL.state.crypt

Description

Encryption or decryption object.

---

Method decrypt_packet

Alert|.packet decrypt_packet(.packet packet, ProtocolVersion version)

Description

Destructively decrypts a packet (including inflating and MAC-verification, if needed). On success, returns the decrypted packet. On failure, returns an alert packet. These cases are distinguished by looking at the is_alert attribute of the returned packet.

---

Method encrypt_packet

Alert|.packet encrypt_packet(.packet packet, ProtocolVersion version)

Description

Encrypts a packet (including deflating and MAC-generation).

---

Variable mac

.Cipher.MACAlgorithm SSL.state.mac

Description

Message Authentication Code

---

Variable seq_num

Gmp.mpz SSL.state.seq_num

Description

64-bit sequence number.

---

Variable session

object SSL.state.session

Description

Information about the used algorithms.

---

Variable tls_iv

int SSL.state.tls_iv

Description

TLS IV prefix length.

Module SSL.Cipher

Description

Encryption and MAC algorithms used in SSL.

---

Method anon_sign

ADT.struct anon_sign(object context, string cookie, ADT.struct struct)

Description

The NULL signing method.

---

Method dsa_sign

ADT.struct dsa_sign(object context, string cookie, ADT.struct struct)

Description

Signing using DSA.

---

Method lookup

array lookup(int suite, ProtocolVersion|int version)

Description

Lookup the crypto parameters for a cipher suite.

Parameter suite

Cipher suite to lookup.

Parameter version

Minor version of the SSL protocol to support.

Returns

Returns 0 (zero) for unsupported combinations. Otherwise returns an array with the following fields:

Array
KeyExchangeType 0	Key exchange method.
CipherSpec 1	Initialized CipherSpec for the suite.

---

Method prf

string prf(string secret, string label, string seed, int len)

Description

The Pseudo Random Function used to derive the secret keys.

---

Method rsa_sign

ADT.struct rsa_sign(object context, string cookie, ADT.struct struct)

Description

Signing using RSA.

---

Method rsa_verify

bool rsa_verify(object context, string cookie, ADT.struct struct, Gmp.mpz signature)

Description

Verify an RSA signature.

Class SSL.Cipher.AES

---

Inherit CBC

inherit Crypto.CBC : CBC

Class SSL.Cipher.CipherAlgorithm

Description

Cipher algorithm interface.

---

Method block_size

int(0..) block_size()

Description

Return the block size for this crypto.

---

Method set_encrypt_key
Method set_decrypt_key

this_program set_encrypt_key(string)
this_program set_decrypt_key(string)

Description

Set the key used for encryption/decryption, and enter encryption mode.

Class SSL.Cipher.CipherSpec

Description

Cipher specification.

---

Variable bulk_cipher_algorithm

program SSL.Cipher.CipherSpec.bulk_cipher_algorithm

Description

The algorithm to use for the bulk of the transfered data.

---

Variable hash_size

int SSL.Cipher.CipherSpec.hash_size

Description

The number of bytes in the MAC hashes.

---

Variable iv_size

int SSL.Cipher.CipherSpec.iv_size

Description

The number of bytes of random data needed for initialization vectors.

---

Variable key_bits

int SSL.Cipher.CipherSpec.key_bits

Description

The effective number of bits in key_material.

This is typically key_material * 8, but for eg DES this is key_material * 7.

---

Variable key_material

int SSL.Cipher.CipherSpec.key_material

Description

The number of bytes of key material used on initialization.

---

Variable mac_algorithm

program SSL.Cipher.CipherSpec.mac_algorithm

Description

The Message Authentication Code to use for the packets.

---

Variable sign

function(object, string, ADT.struct:ADT.struct) SSL.Cipher.CipherSpec.sign

Description

The function used to sign packets.

---

Variable verify

function(object, string, ADT.struct, Gmp.mpz:bool) SSL.Cipher.CipherSpec.verify

Description

The function used to verify the signature for packets.

Class SSL.Cipher.DES

---

Inherit CBC

inherit Crypto.CBC : CBC

Class SSL.Cipher.DES3

---

Inherit CBC

inherit Crypto.CBC : CBC

Class SSL.Cipher.DHKeyExchange

Description

Implements Diffie-Hellman key-exchange.

The following key exchange methods are implemented here: KE_dhe_dss, KE_dhe_rsa and KE_dh_anon.

---

Method create

SSL.Cipher.DHKeyExchange SSL.Cipher.DHKeyExchange(DHParameters p)

Class SSL.Cipher.DHParameters

Description

Diffie-Hellman parameters.

---

Method create

SSL.Cipher.DHParameters SSL.Cipher.DHParameters(object ... args)

---

Variable p
Variable g
Variable order

Gmp.mpz SSL.Cipher.DHParameters.p
Gmp.mpz SSL.Cipher.DHParameters.g
Gmp.mpz SSL.Cipher.DHParameters.order

Class SSL.Cipher.IDEA

---

Inherit CBC

inherit Crypto.CBC : CBC

Class SSL.Cipher.MACAlgorithm

Description

Message Authentication Code interface.

---

Method hash

string hash(object packet, Gmp.mpz seq_num)

Parameter packet

Packet to generate a MAC hash for.

Parameter seq_num

Sequence number for the packet in the stream.

Returns

Returns the MAC hash for the packet.

---

Constant hash_header_size

constant int SSL.Cipher.MACAlgorithm.hash_header_size

Description

The length of the header prefixed by hash().

---

Method hash_raw

string hash_raw(string data)

Description

Hashes the data with the hash algorithm and retuns it as a raw binary string.

Class SSL.Cipher.MAChmac_md5

Description

HMAC using MD5.

This is the MAC algorithm used by TLS 1.0 and later.

---

Method create

SSL.Cipher.MAChmac_md5 SSL.Cipher.MAChmac_md5(string|void s)

---

Inherit MAChmac_sha

inherit MAChmac_sha : MAChmac_sha

Class SSL.Cipher.MAChmac_sha

Description

HMAC using SHA.

This is the MAC algorithm used by TLS 1.0 and later.

---

Method create

SSL.Cipher.MAChmac_sha SSL.Cipher.MAChmac_sha(string|void s)

---

Method hash

string hash(object packet, Gmp.mpz seq_num)

---

Constant hash_header_size

constant int SSL.Cipher.MAChmac_sha.hash_header_size

Description

The length of the header prefixed by hash().

---

Inherit MACAlgorithm

inherit MACAlgorithm : MACAlgorithm

Class SSL.Cipher.MACmd5

Description

MAC using MD5.

Note

Note: This uses the algorithm from the SSL 3.0 draft.

---

Inherit MACsha

inherit MACsha : MACsha

Class SSL.Cipher.MACsha

Description

MAC using SHA.

Note

Note: This uses the algorithm from the SSL 3.0 draft.

---

Method create

SSL.Cipher.MACsha SSL.Cipher.MACsha(string|void s)

---

Method hash

string hash(object packet, Gmp.mpz seq_num)

---

Constant hash_header_size

constant int SSL.Cipher.MACsha.hash_header_size

Description

The length of the header prefixed by hash().

---

Method hash_master

string hash_master(string data, string|void s)

---

Inherit MACAlgorithm

inherit MACAlgorithm : MACAlgorithm

Module SSL.Constants

Description

Protocol constants

---

Constant CIPHER_algorithms

constant SSL.Constants.CIPHER_algorithms

Description

Mapping from cipher algorithm to effective key length.

---

Constant PROTOCOL_major
Constant PROTOCOL_minor

constant int SSL.Constants.PROTOCOL_major
constant int SSL.Constants.PROTOCOL_minor

Description

Max supported SSL version.

Enum SSL.Constants.CompressionType

Description

Compression methods.

---

Constant COMPRESSION_deflate

constant SSL.Constants.COMPRESSION_deflate

Description

Deflate compression.

---

Constant COMPRESSION_lzs

constant SSL.Constants.COMPRESSION_lzs

Description

LZS compression.

---

Constant COMPRESSION_null

constant SSL.Constants.COMPRESSION_null

Description

No compression.

Enum SSL.Constants.KeyExchangeType

Description

Key exchange methods.

---

Constant KE_dh

constant SSL.Constants.KE_dh

Description

Diffie-Hellman

---

Constant KE_dh_anon

constant SSL.Constants.KE_dh_anon

Description

Diffie-Hellman Anonymous

---

Constant KE_dhe_dss

constant SSL.Constants.KE_dhe_dss

Description

Diffie-Hellman DSS

---

Constant KE_dhe_rsa

constant SSL.Constants.KE_dhe_rsa

Description

Diffie-Hellman RSA

---

Constant KE_dms

constant SSL.Constants.KE_dms

---

Constant KE_rsa

constant SSL.Constants.KE_rsa

Description

Rivest-Shamir-Adelman

Enum SSL.Constants.ProtocolVersion

Description

Constants for specifying the versions of SSL to use.

See also

SSL.sslfile()->create(), SSL.handshake()->create()

---

Constant PROTOCOL_SSL_3_0

constant SSL.Constants.PROTOCOL_SSL_3_0

Description

SSL 3.0 - The original SSL3 draft version.

---

Constant PROTOCOL_SSL_3_1

constant SSL.Constants.PROTOCOL_SSL_3_1

Description

SSL 3.1 - The RFC 2246 version of SSL.

---

Constant PROTOCOL_SSL_3_2

constant SSL.Constants.PROTOCOL_SSL_3_2

Description

SSL 3.2 - The RFC 4346 version of SSL.

---

Constant PROTOCOL_TLS_1_0

constant SSL.Constants.PROTOCOL_TLS_1_0

Description

TLS 1.0 - The RFC 2246 version of TLS.

---

Constant PROTOCOL_TLS_1_1

constant SSL.Constants.PROTOCOL_TLS_1_1

Description

TLS 1.1 - The RFC 4346 version of TLS.

Module Standards

Module Standards.ASN1

Module Standards.ASN1.Types

Description

Encodes various asn.1 objects according to the Distinguished Encoding Rules (DER)

---

Variable TaggedType0
Variable TaggedType1
Variable TaggedType2
Variable TaggedType3

MetaExplicit Standards.ASN1.Types.TaggedType0
MetaExplicit Standards.ASN1.Types.TaggedType1
MetaExplicit Standards.ASN1.Types.TaggedType2
MetaExplicit Standards.ASN1.Types.TaggedType3

Description

Some common explicit tags for convenience.

These are typically used to indicate which of several optional fields are present.

Example

Eg RFC 5915 section 3:
ECPrivateKey ::= SEQUENCE {
      version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
      privateKey     OCTET STRING,
      parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
      publicKey  [1] BIT STRING OPTIONAL
    }
The presence of the fields parameters and publicKey above
   are indicated with TaggedType0 and TaggedType1 respectively.

---

Method asn1_IA5_valid

bool asn1_IA5_valid(string s)

---

Method asn1_bmp_valid

bool asn1_bmp_valid(string s)

---

Method asn1_broken_teletex_valid

bool asn1_broken_teletex_valid(string s)

---

Method asn1_printable_valid

bool asn1_printable_valid(string s)

Description

Checks if a Pike string can be encoded as a PrintableString.

---

Method asn1_teletex_valid

bool asn1_teletex_valid(string s)

---

Method asn1_universal_valid

int(0) asn1_universal_valid(string s)

---

Method asn1_utf8_valid

int(1) asn1_utf8_valid(string s)

Description

Checks if a Pike string can be encoded with UTF8. That is always the case...

---

Method extract_cls

int(2bit) extract_cls(int i)

Description

Extract ASN1 type class from a combined tag.

See also

make_combined_tag

---

Method extract_tag

int extract_tag(int i)

Description

Extract ASN1 type tag from a combined tag.

See also

make_combined_tag

---

Method make_combined_tag

int make_combined_tag(int cls, int tag)

Description

Combines tag and class to a single integer, for internal uses.

Parameter cls

ASN1 type class (0..3).

Parameter tag

ASN1 type tag (1..).

Returns

The combined tag.

See also

extract_tag, extract_cls

Class Standards.ASN1.Types.BMPString

Description

BMP String object

Character set: ISO/IEC 10646-1 (compatible with Unicode). Fixed width encoding with 2 octets per character.

FIXME: The encoding is very likely UCS-2, but that's not yet verified.

---

Inherit OctetString

inherit OctetString : OctetString

Class Standards.ASN1.Types.BitString

Description

Bit string object

---

Inherit Object

inherit Object : Object

---

Method set_from_ascii

this_program set_from_ascii(string(8bit) s)

Description

Set the bitstring value as a string with "1" and "0".

---

Method set_length

this_program set_length(int len)

Description

Sets the length of the bit string to len number of bits. Will only work correctly on strings longer than len bits.

---

Variable value

string(8bit) Standards.ASN1.Types.BitString.value

Description

value of object

Class Standards.ASN1.Types.Boolean

Description

boolean object

---

Inherit Object

inherit Object : Object

---

Variable value

int Standards.ASN1.Types.Boolean.value

Description

value of object

Class Standards.ASN1.Types.BrokenTeletexString

Description

(broken) TeletexString object

Encodes and decodes latin1, but labels it TeletexString, as is common in many broken programs (e.g. Netscape 4.0X).

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.Compound

Description

Compound object primitive

---

Variable elements

array(Object) Standards.ASN1.Types.Compound.elements

Description

Contents of compound object.

---

Inherit Object

inherit Object : Object

Class Standards.ASN1.Types.Enumerated

Description

Enumerated object

---

Inherit Integer

inherit Integer : Integer

Class Standards.ASN1.Types.IA5String

Description

IA5 String object

Character set: ASCII. Fixed width encoding with 1 octet per character.

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.Identifier

Description

Object identifier object

---

Method append

this_program append(int ... args)

Description

Returns a new Identifier object with args appended to the ID path.

---

Variable id

array(int) Standards.ASN1.Types.Identifier.id

Description

value of object

---

Inherit Object

inherit Object : Object

Class Standards.ASN1.Types.Integer

Description

Integer object All integers are represented as bignums, for simplicity

---

Inherit Object

inherit Object : Object

---

Variable value

Gmp.mpz Standards.ASN1.Types.Integer.value

Description

value of object

Class Standards.ASN1.Types.MetaExplicit

Description

Meta-instances handle a particular explicit tag and set of types. Once cloned this object works as a factory for Compound objects with the cls and tag that the meta object was initialized with.

Example

MetaExplicit m = MetaExplicit(1,2);
   Compound c = m(Integer(3));

---

Method create

Standards.ASN1.Types.MetaExplicit Standards.ASN1.Types.MetaExplicit(int cls, int tag, mapping(int:program)|void types)

Class Standards.ASN1.Types.Null

Description

Null object

---

Inherit Object

inherit Object : Object

Class Standards.ASN1.Types.Object

Description

Generic, abstract base class for ASN1 data types.

---

Method get_cls

int get_cls()

Description

Get the class of this object.

Returns

The class of this object.

---

Method get_combined_tag

int get_combined_tag()

Description

Get the combined tag (tag + class) for this object.

Returns

the combined tag header

---

Method get_der

string(8bit) get_der()

Description

Get the DER encoded version of this object.

Returns

DER encoded representation of this object.

---

Method get_der_content

string(8bit) get_der_content()

Description

Return the DER payload.

---

Method get_tag

int get_tag()

Description

Get the tag for this object.

Returns

The tag for this object.

Class Standards.ASN1.Types.OctetString

Description

Octet string object

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.PrintableString

Description

PrintableString object

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.Sequence

Description

Sequence object

---

Inherit Compound

inherit Compound : Compound

Class Standards.ASN1.Types.Set

Description

Set object

---

Inherit Compound

inherit Compound : Compound

Class Standards.ASN1.Types.String

Description

string object primitive

---

Inherit Object

inherit Object : Object

---

Variable value

string Standards.ASN1.Types.String.value

Description

value of object

Class Standards.ASN1.Types.TeletexString

Description

TeletexString object

Avoid this one; it seems to be common that this type is used to label strings encoded with the ISO 8859-1 character set (use asn1_broken_teletex_string for that). From http://www.mindspring.com/~asn1/nlsasn.htm:

/.../ Types GeneralString, VideotexString, TeletexString (T61String), and GraphicString exist in earlier versions [pre-1994] of ASN.1. They are considered difficult to use correctly by applications providing national language support. Varying degrees of application support for T61String values seems to be most common in older applications. Correct support is made more difficult, as character values available in type T61String have changed with the addition of new register entries from the 1984 through 1997 versions.

This implementation is based on the description of T.61 and T.51 in "Some functions for representing T.61 characters from the X.500 Directory Service in ISO 8859 terminals (Version 0.2. July 1994.)" by Enrique Silvestre Mora (mora@si.uji.es), Universitat Jaume I, Spain, found in the package ftp://pereiii.uji.es/pub/uji-ftp/unix/ldap/iso-t61.translation.tar.Z

The translation is only complete for 8-bit latin 1 strings. It encodes strictly to T.61, but decodes from the superset T.51.

Note

CCITT Recommendation T.61 is also known as ISO-IR 103:1985 (graphic characters) and ISO-IR 106:1985 and ISO-IR 107:1985 (control characters).

See also

Charset

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.UTC

Description

UTCTime

RFC 2459 section 4.1.2.5.1.

---

Method get_posix

int get_posix()

---

Inherit String

inherit String : String

---

Method set_posix

this_program set_posix(int t)

Class Standards.ASN1.Types.UTF8String

Description

UTF8 string object

Character set: ISO/IEC 10646-1 (compatible with Unicode).

Variable width encoding, see RFC 2279.

---

Inherit String

inherit String : String

Class Standards.ASN1.Types.UniversalString

Description

Universal String object

Character set: ISO/IEC 10646-1 (compatible with Unicode). Fixed width encoding with 4 octets per character.

FIXME

The encoding is very likely UCS-4, but that's not yet verified.

---

Inherit OctetString

inherit OctetString : OctetString

Class Standards.ASN1.Types.VisibleString

---

Inherit String

inherit String : String

Module Standards.PKCS

Module Standards.PKCS.Signature

---

Method build_digestinfo

string build_digestinfo(string msg, Crypto.Hash hash)

Description

Construct a PKCS-1 digestinfo.

Parameter msg

message to digest

Parameter hash

crypto hash object such as Crypto.SHA1 or Crypto.MD5

See also

Crypto.RSA()->sign

Module Stdio

Description

Pike 7.8 compatibility predef::Stdio implementation.

The main difference from later versions of Pike is that Stdio.File and Stdio.FILE use proxy functions defined in _Stdio.Fd_ref, instead of accessing the file descriptors directly.

---

Inherit Stdio

inherit 7.9::Stdio : Stdio

Class Stdio.FILE

Description

Stdio.FILE is a buffered version of Stdio.File, it inherits Stdio.File and has most of the functionality of Stdio.File. However, it has an input buffer that allows line-by-line input.

It also has support for automatic charset conversion for both input and output (see Stdio.FILE()->set_charset()).

Note

The output part of Stdio.FILE is currently not buffered.

---

Method _get_iterator

Stdio.FILE a;
foreach( a; index; value ) or
protected object _get_iterator()

Description

Returns an iterator that will loop over the lines in this file.

See also

line_iterator()

---

Method getchar

local int getchar()

Description

This function returns one character from the input stream.

Returns

Returns the ISO-10646 (Unicode) value of the character.

Note

Returns an int and not a string of length 1.

---

Method gets

string gets(bool|void not_all)

Description

Read one line of input with support for input conversion.

Parameter not_all

Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.

Returns

This function returns the line read if successful, and 0 if no more lines are available.

See also

ngets(), read(), line_iterator(), set_charset()

---

Inherit file

inherit File : file

---

Method line_iterator

object line_iterator(int|void trim)

Description

Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.

Note

It's not supported to call this method more than once unless a call to seek is done in advance. Also note that it's not possible to intermingle calls to read, gets or other functions that read data with the line iterator, it will produce unexpected results since the internal buffer in the iterator will not contain sequential file-data in those cases.

See also

_get_iterator()

---

Method ngets

array(string) ngets(void|int(1..) n, bool|void not_all)

Description

Get n lines.

Parameter n

Number of lines to get, or all remaining if zero.

Parameter not_all

Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.

---

Method openat

FILE openat(string filename, string mode)
FILE openat(string filename, string mode, int mask)

Description

Same as Stdio.File()->openat(), but returns a Stdio.FILE object.

See also

Stdio.File()->openat()

---

Method pipe

File pipe(int|void flags)

Description

Same as Stdio.File()->pipe().

Note

Returns an Stdio.File object, NOT an Stdio.FILE object.

In future releases of Pike this will most likely change to returning an Stdio.FILE object. This is already the case if STDIO_DIRECT_FD has been defined.

---

Method printf

int printf(string format, mixed ... data)

Description

This function does approximately the same as: write(sprintf(format,@data)).

See also

write(), sprintf()

---

Method read

string read(int|void bytes, void|bool now)

Description

Read bytes (wide-) characters with buffering and support for input conversion.

See also

Stdio.File()->read(), set_charset(), unread()

---

Method set_charset

void set_charset(string|void charset)

Description

Sets the input and output charset of this file to the specified charset. If charset is 0 or not specified the environment is used to try to detect a suitable charset.

The default charset if this function is not called is "ISO-8859-1".

FIXME

Consider using one of ISO-IR-196 ("\e%G" - switch to UTF-8 with return) or ISO-IR-190 ("\e%/G" - switch to UTF-8 level 1 no return) or ISO-IR-191 ("\e%/H" - switch to UTF-8 level 2 no return) or ISO-IR-192 ("\e%/I" - switch to UTF-8 level 3 no return) or ISO-IR-193 ("\e%/J" - switch to UTF-16 level 1 no return) or ISO-IR-194 ("\e%/K" - switch to UTF-16 level 2 no return) or ISO-IR-195 ("\e%/L" - switch to UTF-16 level 3 no return) or ISO-IR-162 ("\e%/@" - switch to UCS-2 level 1) or ISO-IR-163 ("\e%/A" - switch to UCS-4 level 1) or ISO-IR-174 ("\e%/C" - switch to UCS-2 level 2) or ISO-IR-175 ("\e%/D" - switch to UCS-4 level 2) or ISO-IR-176 ("\e%/E" - switch to UCS-2 level 3) or ISO-IR-177 ("\e%/F" - switch to UCS-4 level 3) or ISO-IR-178 ("\e%B" - switch to UTF-1) automatically to encode wide strings.

---

Method ungets

void ungets(string s)

Description

This function puts a line back in the input buffer. The line can then be read with eg read(), gets() or getchar().

Note

The string is autoterminated by an extra line-feed.

See also

read(), gets(), getchar(), unread()

---

Method unread

void unread(string s)

Description

This function puts a string back in the input buffer. The string can then be read with eg read(), gets() or getchar().

See also

read(), gets(), getchar(), ungets()

---

Method write

int write(array(string)|string what, mixed ... fmt)

Description

Write what with support for output_conversion.

See also

Stdio.File()->write()

Class Stdio.File

Description

This is the basic I/O object, it provides socket and pipe communication as well as file access. It does not buffer reads and writes or provide line-by-line reading, that is done with Stdio.FILE object.

Note

The file or stream will normally be closed when this object is destructed (unless there are more objects that refer to the same file through use of assign or dup). Objects do not contain cyclic references in themselves, so they will be destructed timely when they run out of references.

See also

Stdio.FILE

---

Method assign

int assign(File|Fd o)

Description

This function takes a clone of Stdio.File and assigns all variables of this file from it. It can be used together with dup() to move files around.

See also

dup()

---

Method async_connect

int async_connect(string host, int|string port, function(int, mixed ... :void) callback, mixed ... args)

Description

Open a TCP/IP connection asynchronously.

This function is similar to connect(), but works asynchronously.

Parameter host

Hostname or IP to connect to.

Parameter port

Port number or service name to connect to.

Parameter callback

Function to be called on completion. The first argument will be 1 if a connection was successfully established, and 0 (zero) on failure. The rest of the arguments to callback are passed verbatim from args.

Parameter args

Extra arguments to pass to callback.

Returns

Returns 0 on failure, and 1 if callback will be used.

Note

The socket may be opened with open_socket() ahead of the call to this function, but it is not required.

Note

This object is put in callback mode by this function. For callback to be called, the backend must be active. See e.g. set_read_callback for more details about backends and callback mode.

Note

The socket will be in nonblocking state if the connection is successful, and any callbacks will be cleared.

See also

connect(), open_socket(), set_nonblocking()

---

Method close

int close()
int close(string direction)

Description

Close the file. Optionally, specify "r", "w" or "rw" to close just the read, just the write or both read and write directions of the file respectively.

An exception is thrown if an I/O error occurs.

Returns

Nonzero is returned if the file wasn't open in the specified direction, zero otherwise.

Note

This function will not call the close_callback.

See also

open, open_socket

---

Method connect

int connect(string host, int|string port, void|string client, void|int|string client_port)

Description

This function connects a socket previously created with open_socket() to a remote socket through TCP/IP. The host argument is the hostname or IP number of the remote machine. A local IP and port can be explicitly bound by specifying client and client_port.

Returns

This function returns 1 for success, 0 otherwise.

Note

In nonblocking mode 0 (zero) may be returned and errno() set to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded as a connection failure. In nonblocking mode you need to wait for a write or close callback before you know if the connection failed or not.

See also

query_address(), async_connect(), connect_unix()

---

Method connect_unix

int connect_unix(string path)

Description

Open a UNIX domain socket connection to the specified destination.

Returns

Returns 1 on success, and 0 on failure.

Note

Nonblocking mode is not supported while connecting

---

Method create

Stdio.File Stdio.File()
Stdio.File Stdio.File(string filename)
Stdio.File Stdio.File(string filename, string mode)
Stdio.File Stdio.File(string filename, string mode, int mask)
Stdio.File Stdio.File(string descriptorname)
Stdio.File Stdio.File(int fd)
Stdio.File Stdio.File(int fd, string mode)

Description

There are four basic ways to create a Stdio.File object. The first is calling it without any arguments, in which case the you'd have to call open(), connect() or some other method which connects the File object with a stream.

The second way is calling it with a filename and open mode. This is the same thing as cloning and then calling open(), except shorter and faster.

The third way is to call it with descriptorname of "stdin", "stdout" or "stderr". This will open the specified standard stream.

For the advanced users, you can use the file descriptors of the systems (note: emulated by pike on some systems - like NT). This is only useful for streaming purposes on unix systems. This is not recommended at all if you don't know what you're into. Default mode for this is "rw".

Note

Open mode will be filtered through the system UMASK. You might need to use chmod() later.

See also

open(), connect(), Stdio.FILE,

---

Method dup

File dup()

Description

This function returns a clone of Stdio.File with all variables copied from this file.

Note

All variables, even id, are copied.

See also

assign()

---

Method errno

int errno()

Description

Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.

---

Inherit Fd_ref

optional inherit _Stdio.Fd_ref : Fd_ref

---

Method line_iterator

String.SplitIterator|LineIterator line_iterator(int|void trim)

Description

Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.

---

Method open

int open(string filename, string mode)
int open(string filename, string mode, int mask)

Description

Open a file for read, write or append. The parameter mode should contain one or more of the following letters:

"r"	Open file for reading.
"w"	Open file for writing.
"a"	Open file for append (use with "w").
"t"	Truncate file at open (use with "w").
"c"	Create file if it doesn't exist (use with "w").
"x"	Fail if file already exists (use with "c").

mode should always contain at least one of the letters "r" or "w".

The parameter mask is protection bits to use if the file is created. Default is 0666 (read+write for all in octal notation).

Returns

This function returns 1 for success, 0 otherwise.

See also

close(), create()

---

Method open_socket

int open_socket(int|string|void port, string|void address, int|string|void family_hint)

Description

This makes this file into a socket ready for connections. The reason for this function is so that you can set the socket to nonblocking or blocking (default is blocking) before you call connect().

Parameter port

If you give a port number to this function, the socket will be bound to this port locally before connecting anywhere. This is only useful for some silly protocols like FTP. The port can also be specified as a string, giving the name of the service associated with the port. Pass -1 to not specify a port (eg to bind only to an address).

Parameter address

You may specify an address to bind to if your machine has many IP numbers.

Parameter family_hint

A protocol family for the socket can be specified. If no family is specified, one which is appropriate for the address is automatically selected. Thus, there is normally no need to specify it. If you do not want to specify a bind address, you can provide the address as a hint here instead, to allow the automatic selection to work anyway.

Returns

This function returns 1 for success, 0 otherwise.

See also

connect(), set_nonblocking(), set_blocking()

---

Method openat

File openat(string filename, string mode)
File openat(string filename, string mode, int mask)

Description

Open a file relative to an open directory.

See also

File.statat(), File.unlinkat()

---

Method openpt

int openpt(string mode)

Description

Open the master end of a pseudo-terminal pair. The parameter mode should contain one or more of the following letters:

"r"	Open terminal for reading.
"w"	Open terminal for writing.

mode should always contain at least one of the letters "r" or "w".

See also

grantpt()

---

Method pipe

File pipe(void|int required_properties)

Description

This function creates a pipe between the object it was called in and an object that is returned.

Parameter required_properties

Binary or (predef::`|()) of required PROP_ properties.

PROP_IPC	The resulting pipe may be used for inter process communication.
PROP_NONBLOCK	The resulting pipe supports nonblocking I/O.
PROP_SHUTDOWN	The resulting pipe supports shutting down transmission in either direction (see close()).
PROP_BUFFERED	The resulting pipe is buffered (usually 4KB).
PROP_BIDIRECTIONAL	The resulting pipe is bi-directional.
PROP_SEND_FD	The resulting pipe might support sending of file descriptors (see send_fd() and receive_fd() for details).
PROP_REVERSE	The resulting pipe supports communication "backwards" (but not necessarily "forwards", see PROP_BIDIRECTIONAL).

The default is PROP_NONBLOCK|PROP_BIDIRECTIONAL.

If PROP_BIDIRECTIONAL isn't specified, the read-end is this object, and the write-end is the returned object (unless PROP_REVERSE has been specified, in which case it is the other way around).

The two ends of a bi-directional pipe are indistinguishable.

If the File object this function is called in was open to begin with, it will be closed before the pipe is created.

Note

Calling this function with an argument of 0 is not the same as calling it with no arguments.

See also

Process.create_process(), send_fd(), receive_fd(), PROP_IPC, PROP_NONBLOCK, PROP_SEND_FD, PROP_SHUTDOWN, PROP_BUFFERED, PROP_REVERSE, PROP_BIDIRECTIONAL

---

Method query_read_callback
Method query_write_callback
Method query_read_oob_callback
Method query_write_oob_callback
Method query_close_callback
Method query_callbacks

function(mixed, string:int) query_read_callback()
function(mixed:int) query_write_callback()
function(mixed, string:int) query_read_oob_callback()
function(mixed:int) query_write_oob_callback()
function(mixed:int) query_close_callback()
array(function(mixed, void|string:int)) query_callbacks()

Description

These functions return the currently installed callbacks for the respective events.

query_callbacks returns the callbacks in the same order as set_callbacks and set_nonblocking expect them.

See also

set_nonblocking(), set_read_callback, set_write_callback, set_read_oob_callback, set_write_oob_callback, set_close_callback, set_callbacks

---

Method query_id

mixed query_id()

Description

This function returns the id that has been set with set_id().

See also

set_id()

---

Method read_function

function(:string) read_function(int nbytes)

Description

Returns a function that when called will call read with nbytes as argument. Can be used to get various callback functions, eg for the fourth argument to String.SplitIterator.

---

Method send_fd

void send_fd(File|Fd file)

---

Method set_blocking

void set_blocking()

Description

This function clears all callbacks and sets a stream to blocking mode. i.e. reading, writing and closing will wait until data has been transferred before returning.

Note

The callbacks are cleared and blocking mode is set in one atomic operation, so no callback gets called in between if the backend is running in another thread.

Even so, if the stream is in callback mode (i.e. if any callbacks are installed) then only the backend thread can use this function reliably; it might otherwise already be running in a callback which is about to call e.g. write when the stream becomes blocking.

See also

set_nonblocking(), set_nonblocking_keep_callbacks(), set_blocking_keep_callbacks()

---

Method set_nonblocking_keep_callbacks
Method set_blocking_keep_callbacks

void set_nonblocking_keep_callbacks()
void set_blocking_keep_callbacks()

Description

Toggle between blocking and nonblocking, without changing the callbacks.

See also

set_nonblocking(), set_blocking()

---

Method set_callbacks

void set_callbacks(void|function(mixed, string:int) read_cb, void|function(mixed:int) write_cb, void|function(mixed:int) close_cb, void|function(mixed, string:int) read_oob_cb, void|function(mixed:int) write_oob_cb)

Description

Installs all the specified callbacks at once. Use UNDEFINED to keep the current setting for a callback.

Like set_nonblocking, the callbacks are installed atomically. As opposed to set_nonblocking, this function does not do anything with the stream, and it doesn't even have to be open.

See also

set_read_callback, set_write_callback, set_read_oob_callback, set_write_oob_callback, set_close_callback, query_callbacks

---

Method set_read_callback
Method set_write_callback
Method set_read_oob_callback
Method set_write_oob_callback
Method set_close_callback
Method set_fs_event_callback

void set_read_callback(function(mixed, string:int) read_cb)
void set_write_callback(function(mixed:int) write_cb)
void set_read_oob_callback(function(mixed, string:int) read_oob_cb)
void set_write_oob_callback(function(mixed:int) write_oob_cb)
void set_close_callback(function(mixed:int) close_cb)
void set_fs_event_callback(function(mixed, int:int) fs_event_cb, int event_mask)

Description

These functions set the various callbacks, which will be called when various events occur on the stream. A zero as argument will remove the callback.

A Pike.Backend object is responsible for calling the callbacks. It requires a thread to be waiting in it to execute the calls. That means that only one of the callbacks will be running at a time, so you don't need mutexes between them.

Unless you've specified otherwise with the set_backend function, the default backend Pike.DefaultBackend will be used. It's normally activated by returning -1 from the main function and will then execute in the main thread.

• When data arrives on the stream, read_cb will be called with some or all of that data as the second argument.

• When the stream has buffer space over for writing, write_cb will be called so that you can write more data to it.

  This callback is also called after the remote end of a socket connection has closed the write direction. An attempt to write data to it in that case will generate a System.EPIPE errno. If the remote end has closed both directions simultaneously (the usual case), Pike will first attempt to call close_cb, then this callback (unless close_cb has closed the stream).

• When out-of-band data arrives on the stream, read_oob_cb will be called with some or all of that data as the second argument.

• When the stream allows out-of-band data to be sent, write_oob_cb will be called so that you can write more out-of-band data to it.

  If the OS doesn't separate the write events for normal and out-of-band data, Pike will try to call write_oob_cb first. If it doesn't write anything, then write_cb will be tried. This also means that write_oob_cb might get called when the remote end of a connection has closed the write direction.

• When an error or an end-of-stream in the read direction occurs, close_cb will be called. errno will return the error, or zero in the case of an end-of-stream.

  The name of this callback is rather unfortunate since it really has nothing to do with a close: The stream is still open when close_cb is called (you might not be able to read and/or write to it, but you can still use things like query_address, and the underlying file descriptor is still allocated). Also, this callback will not be called for a local close, neither by a call to close or by destructing this object.

  Also, close_cb will not be called if a remote close only occurs in the write direction; that is handled by write_cb (or possibly write_oob_cb).

  Events to read_cb and close_cb will be automatically deregistered if an end-of-stream occurs, and all events in the case of an error. I.e. there won't be any more calls to the callbacks unless they are reinstalled. This doesn't affect the callback settings - query_read_callback et al will still return the installed callbacks.

If the stream is a socket performing a nonblocking connect (see open_socket and connect), a connection failure will call close_cb, and a successful connect will call either read_cb or write_cb as above.

All callbacks will receive the id set by set_id as first argument.

If a callback returns -1, no other callback or call out will be called by the backend in that round. I.e. the caller of the backend will get control back right away. For the default backend that means it will immediately start another round and check files and call outs anew.

Parameter event_mask

An event mask specifing bitwise OR of one or more event types to monitor, selected from Stdio.NOTE_WRITE and friends.

Note

These functions do not set the file nonblocking.

Note

Callbacks are also set by set_callbacks and set_nonblocking().

Note

After a callback has been called, it's disabled until it has accessed the stream accordingly, i.e. the write_cb callback is disabled after it's been called until something has been written with write, and the write_oob_cb callback is likewise disabled until something has been written with write_oob. Since the data already has been read when the read callbacks are called, this effect is not noticeable for them.

Note

Installing callbacks means that you will start doing I/O on the stream from the thread running the backend. If you are running these set functions from another thread you must be prepared that the callbacks can be called immediately by the backend thread, so it might not be safe to continue using the stream in this thread.

Because of that, it's useful to talk about "callback mode" when any callback is installed. In callback mode the stream should be seen as "bound" to the backend thread. For instance, it's only the backend thread that reliably can end callback mode before the stream is "handed over" to another thread.

Note

Callback mode has nothing to do with nonblocking mode - although the two often are used together they don't have to be.

Note

The file object will stay referenced from the backend object as long as there are callbacks that can receive events.

Bugs

Setting a close callback without a read callback currently only works when there's no risk of getting more data on the stream. Otherwise the close callback will be silently deregistered if data arrives.

Note

fs_event callbacks only trigger on systems that support these events. Currently, this includes systems that use kqueue, such as Mac OS X, and various flavours of BSD.

See also

set_callbacks, set_nonblocking(), set_id(), set_backend, query_read_callback, query_write_callback, query_read_oob_callback, query_write_oob_callback, query_close_callback

---

Method set_id

void set_id(mixed id)

Description

This function sets the id of this file. The id is mainly used as an identifier that is sent as the first argument to all callbacks. The default id is 0 (zero). Another possible use of the id is to hold all data related to this file in a mapping or array.

See also

query_id()

---

Method set_nonblocking

void set_nonblocking(function(mixed, string:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback)
void set_nonblocking(function(mixed, string:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback, function(mixed, string:int) read_oob_callback, function(mixed:int) write_oob_callback)
void set_nonblocking()

Description

This function sets a stream to nonblocking mode and installs the specified callbacks. See the set_*_callback functions for details about them. If no arguments are given, the callbacks will be cleared.

Note

As opposed to calling the set callback functions separately, this function will set all the callbacks and nonblocking mode atomically so that no callback gets called in between. That avoids races in case the backend is executed by another thread.

Note

Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.

See also

set_blocking(), set_callbacks, set_read_callback(), set_write_callback(), set_read_oob_callback(), set_write_oob_callback(), set_close_callback() set_nonblocking_keep_callbacks(), set_blocking_keep_callbacks()

Class Stdio.Port

Description

Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.

---

Method accept

File accept()

Description

This function completes a connection made from a remote machine to this port. It returns a two-way stream in the form of a clone of Stdio.File. The new file is by initially set to blocking mode.

See also

Stdio.File

---

Method create

Stdio.Port Stdio.Port()
Stdio.Port Stdio.Port(int|string port)
Stdio.Port Stdio.Port(int|string port, function(:void) accept_callback)
Stdio.Port Stdio.Port(int|string port, function(:void) accept_callback, string ip)
Stdio.Port Stdio.Port("stdin")
Stdio.Port Stdio.Port("stdin", function(:void) accept_callback)

Description

If the first argument is other than "stdin" the arguments will be passed to bind().

When create is called with "stdin" as the first argument, a socket is created out of the file descriptor 0. This is only useful if it actually is a socket to begin with.

See also

bind

---

Inherit _port

inherit _Stdio._port : _port

Module files

Description

Pike 7.8 compatibility.

In 7.8 and earlier "_Stdio" was named "files".

---

Inherit _Stdio

inherit _Stdio : _Stdio