Pike Manual

Module Builtin

Inherit Builtin: inherit _static_modules.Builtin : Builtin

Method _get_setter: function(mixed:void)|zero_get_setter(objecto, stringvarname)
Description: Get a setter for the variable named varname in object o.
Returns: Returns a Setter()->`()() for the variable if it exists, and UNDEFINED otherwise.
See also: object_variablep()

Method _take_over_initial_predefines

mapping(string:mixed) _take_over_initial_predefines()

Description

Returns a mapping containing the set of predefined macros. These are typically the macros defined via the -D option when starting Pike.

This function is typically called by the MasterObject at initialization, and may only be called once. After it has been called, cpp() will start calling CompilationHandler->get_predefines() to retrieve the set of predefined macros.

See also

[cpp()], CompilationHandler->get_predefines()

Class Builtin.FakeObject

Description

Used as a place holder in eg backtraces for objects that are unsuitable to have references to in backtraces.

Examples of such objects are instances of Thread.MutexKey, and Nettle.Cipher.State.

See also

backtrace()

Class Builtin.Null

Description: This class is used to implement the low-level aspects of Val.Null.
Note: This class should typically not be used directly. Use Val.Null instead.
Note: This class was previously available as Sql.Null. Any such use should be replaced with Val.Null.
Deprecated: Replaced by Val.Null.
See also: Val.Null, Val.null

Constant is_sql_null: constantint Builtin.Null.is_sql_null
Description: SQL Null marker.
Deprecated: Replaced by is_val_null.

Constant is_val_null: constantint Builtin.Null.is_val_null
Description: Nonzero recognition constant.

Method encode_json: stringencode_json()
Description: Defined for use with Standards.JSON.encode, so that it formats NULL as null.

Class Builtin.Pointer

Description: This class is used to implement the low-level aspects of Val.Pointer.
Note: This class should typically not be used directly. Use Val.Pointer instead.
See also: Val.Pointer

Class Builtin.RandomInterface

Method random

arrayrandom(mappingm)

Description

Returns a random index-value pair from the mapping.

Array
`mixed0`	The index of the mapping entry.
`mixed1`	The value f the mapping entry.

Throws

Throws an exception if the mapping is empty.

Method random: floatrandom(floatmax)
Description: This function returns a random number in the range 0 .. max-ɛ.
See also: Random

Method random: intrandom(intmax)
Description: This function returns a random number in the range 0 .. max-1.
See also: Random

Method random: mixedrandom(objecto)
Description: If random is called with an object, lfun::_random will be called in the object.
Throws: Throws an exception if the object doesn't have a _random method.
See also: lfun::_random()

Method random: mixedrandom(array|multisetx)
Description: Returns a random element from x.
Throws: Throws an exception if the array or multiset is empty.

Method random_string

string(8bit)random_string(int(0..))

Description

Prototype for the randomness generating function.

Override this symbol to implement a usable class.

Class Builtin.RandomSystem

Inherit RandomInterface: inherit RandomInterface : RandomInterface

Method random_string

string(8bit)random_string(int(0..)len)

Description

Return a string of random data from the system randomness pool.

On POSIX platforms this reads random data from /dev/urandom on other platforms it may use other methods.

Throws

May throw errors on unexpected state.

Class Builtin.Setter

Description

Internal class for implementing setters.

This class is used by _get_setter().

See also

_get_setter()

Method `()

void res = Builtin.Setter()()

Description

Set the variable for the setter to val.

This is the function returned by _get_setter().

Class Builtin.__Backtrace_Tester__

Description

Class that throws an error during early initialization.

This class is only intended to be used by the Pike testsuite to test that errors triggered in that phase do not trigger bugs in the runtime.

Class Builtin.__master

Description: Used to prototype the master object.

Method _main: void_main(array(string) argv, array(string) env)

Method cast_to_object: objectcast_to_object(stringoname, stringcurrent_file)

Method cast_to_program: programcast_to_program(stringpname, stringcurrent_file, object|voidhandler)

Method compile_error: voidcompile_error(stringfile, intline, stringerr)

Method compile_warning: voidcompile_warning(stringfile, intline, stringwarn)

Method decode_charset: stringdecode_charset(stringdata, stringcharset)

Method describe_backtrace: stringdescribe_backtrace(object|arraytrace, int|voidline_width)

Method handle_error: voidhandle_error(array|objecttrace)

Method handle_import: mixedhandle_import(stringwhat, string|voidcurrent_file, object|voidhandler)

Method handle_include: stringhandle_include(stringf, stringcurrent_file, boollocal_include)

Method handle_inherit: programhandle_inherit(stringpname, stringcurrent_file, object|voidhandler)

Method read_include: stringread_include(stringpath)

Method resolv: mixedresolv(stringidentifier, string|voidcurrent_file, object|voidhandler)

Method werror: voidwerror(stringfmt, mixed ... args)

Method write: voidwrite(stringfmt, mixed ... args)

Class Builtin.automap_marker

Description

This is an internal class used by __automap__().

It may show up during module dumping or in backtraces and the like.

It should in normal circumstances never be used directly.

See also

__automap__(), map()

Method create: Builtin.automap_markerBuiltin.automap_marker(arrayarr, intdepth)
Parameter arr: Array that __automap__() is to loop over.
Parameter depth: Recursion depth of arr where the loop will be.

Class Builtin.pike_trampoline

Description: Internal class used to implement trampoline functions.

Module __builtin

Description

Low-level modules.

This module contains various base classes that are intended to be inherited and/or used from C-code.

Some of the base classes are:

__builtin.Nettle.BlockCipher
Base class for block cipher algorithms.
__builtin.Sql.Connection
Base class for connections to SQL servers. It is a generic interface on top of which the DB server specific implement their specifics.
__builtin.Stack (aka ADT.LowLevelStack)
Simple stack implementation.

Inherit Builtin: inherit _static_modules.Builtin : Builtin

Constant Stack: constantprogram __builtin.Stack
Description: Simple stack implementation.
Note: Do not use this class. Use either ADT.LowLevelStack or ADT.Stack instead.
See also: ADT.LowLevelStack, ADT.Stack

Module __builtin.Nettle

Class __builtin.Nettle.AE

Description

Base class for AE (Authenticated Encryption) algorithms.

AE algorithms behave like a combination of a Cipher and a HMAC.

Note that no actual AE algorithm is implemented in the base class. They are implemented in classes that inherit this class.

See also

AEAD

Inherit Cipher: inherit __builtin.Nettle.Cipher : Cipher

Method `(): State res = __builtin.Nettle.AE()()
Description: Calling `() will return a State object.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Class __builtin.Nettle.AE.State

Description

This is the context for a single incrementally updated AE cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Inherit State: inherit Cipher::State : State

Method digest: string(8bit)digest(int|voidlength)
Description: Generates a digest, and resets the hashing contents.
Parameter length: If the length argument is provided, the digest is truncated to the given length.
Returns: The digest.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Class __builtin.Nettle.AEAD

Description

Base class for AEAD (Authenticated Encryption with Associated Data) algorithms.

AEAD algorithms behave like a combination of a Cipher and a HMAC.

Note that no actual AEAD algorithm is implemented in the base class. They are implemented in classes that inherit this class.

See also

AE

Inherit AE: inherit __builtin.Nettle.AE : AE

Inherit __Hash: inherit __builtin.Nettle.__Hash : __Hash

Method `(): State res = __builtin.Nettle.AEAD()()
Description: Calling `() will return a State object.

Class __builtin.Nettle.AEAD.State

Description

This is the context for a single incrementally updated AEAD cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Inherit State: inherit Cipher::State : State

Inherit State: inherit __Hash::State : State

Class __builtin.Nettle.BlockCipher

Description

Base class for block cipher algorithms.

Implements some common convenience functions, and prototypes.

It also implements operating modes other than ECB.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit this class.

Inherit Cipher: inherit .Cipher : Cipher

Module __builtin.Nettle.BlockCipher.CTR

Description

Implementation of Counter Mode (CTR). Works as a wrapper for the cipher algorithm in the parent module.

This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).

See also

predef::Nettle.BlockCipher.CBC, predef::Nettle.BlockCipher16.CCM, predef::Nettle.BlockCipher16.GCM, MAC

Inherit Cipher: inherit .Cipher : Cipher

Method name: string(7bit)name()
Description: Returns the name of the base cipher extended with ".CTR".

Class __builtin.Nettle.BlockCipher.CTR.State

Description: The state for the embedded algorithm

Inherit this_program: inherit ::this_program : this_program

Class __builtin.Nettle.BlockCipher16Mixin

Description

Mixin class for block cipher algorithms that have a 16 byte block size.

Implements some common convenience functions, and prototypes.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that (indirectly) inherit this class.

Class __builtin.Nettle.Cipher

Description

Base class for cipher algorithms.

Implements some common convenience functions, and prototypes.

Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit (usually via predef::Nettle.Cipher) this class.

See also

predef::Nettle.Cipher, Crypto.Cipher

Method `(): State res = __builtin.Nettle.Cipher()()
Description: Calling `() will return a State object.

Method block_size: int(0..)block_size()
Returns: The block size of the cipher (1 for stream ciphers).

Method decrypt: stringdecrypt(string(8bit)key, string(8bit)data)
Description: Works as a shortcut for obj->set_decrypt_key(key)->crypt(data)

Method encrypt: stringencrypt(string(8bit)key, string(8bit)data)
Description: Works as a shortcut for obj->set_encrypt_key(key)->crypt(data)

Method key_size: int(0..)key_size()
Returns: The recommended key size for the cipher.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Class __builtin.Nettle.Cipher.State

Description

This is the context for a single incrementally updated cipher.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Method block_size

int(0..)block_size()

Returns

The block size of the cipher (1 for stream ciphers).

Defaults to just returning global::block_size().

Method crypt: string(8bit)crypt(string(8bit)data)
Description: Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.
Parameter data: For block ciphers, data must be an integral number of blocks.
Returns: The encrypted or decrypted data.

Method key_size

int(0..)key_size()

Returns

The actual key size for this cipher.

Defaults to just returning global::key_size().

Method make_key: string(8bit)make_key()
Description: Generate a key by calling random_string and initialize the object for encryption with that key.
Returns: The generated key.
See also: set_encrypt_key

Method name

string(7bit)name()

Description

Returns a human readable name for the algorithm.

Defaults to just returning global::name().

Method set_decrypt_key: this_programset_decrypt_key(string(8bit)key, void|intforce)
Description: Initializes the object for decryption.
See also: set_encrypt_key, crypt

Method set_encrypt_key: this_programset_encrypt_key(string(8bit)key, void|intforce)
Description: Initializes the object for encryption.
See also: set_decrypt_key, crypt

Class __builtin.Nettle.ECC_Curve

Description: Base class for Elliptic Curve Definitions.
See also: Crypto.ECC.Curve, Nettle.ECC_Curve

Method jose_name: string(7bit)jose_name()
Description: Return the JOSE name of the Curve (if any).
Returns: The default implementation returns UNDEFINED.

Method name: externstring(7bit)name()
Description: Return the name of the Curve.

Method new_scalar: string(8bit)|Gmp.mpznew_scalar(function(int(0..):string(8bit)) rnd)
Description: Generate a new scalar suitable for use as an ECDSA private key or as an ECDH secret factor.
Note: Returns the scalar in the preferred representation for the Curve.

Method size: externintsize()
Description: Return the size in bits of a single coordinate on the curve.

Class __builtin.Nettle.ECC_Curve.Point

Description: Base class for a point on an elliptic curve.

Method create

__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point()
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Pointp)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(mapping(string(7bit):int|Gmp.mpz|string(8bit)) p)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(mapping(string(7bit):string(7bit)) jwk)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Gmp.mpz|intx, Gmp.mpz|inty)
__builtin.Nettle.ECC_Curve.Point__builtin.Nettle.ECC_Curve.Point(Stdio.Buffer|string(8bit)data)

Description

Initialize the object and optionally also select a point on the curve.

The point on the curve can be selected via either via specifying the two coordinates explicitly, or via

`Point`	A `Point` on the same `Crypto.ECC.Curve` to copy.
`mapping(string(7bit):int\|Gmp.mpz)`	A mapping with integer coordinates `"x"` and `"y"`.
`mapping(string(7bit):string(7bit))`	A mapping representing a JWK for the `Point` on the same `Crypto.ECC.Curve`.
`mapping(string(7bit):string(8bit))`	A mapping with coordinates `"x"` and `"y"` in big-endian.
`Stdio.Buffer\|string(8bit)`	The ANSI x9.62 representation of the `Point`. Cf `encode()`.

Note

Throws errors if the point isn't on the Crypto.ECC.Curve.

Method encode

stringencode()

Description

Serialize the Point.

The default implementation serializes according to ANSI x9.62 encoding #4 (uncompressed point format).

Method get_curve: global::this_programget_curve()
Description: Get the Crypto.ECC.Curve that this Point belongs to.

Method get_x
Method get_y: externGmp.mpz|string(8bit)get_x()
externGmp.mpz|string(8bit)get_y()
Description: Get the coordinates for the curve in the preferred representation.

Method get_x_num: Gmp.mpzget_x_num()
Description: Get the numeric representation of the x coordinate.

Method get_x_str: string(8bit)get_x_str()
Description: Get the canonic string representation of the x coordinate.

Method get_y_num: Gmp.mpzget_y_num()
Description: Get the numeric representation of the y coordinate.

Method get_y_str: string(8bit)get_y_str()
Description: Get the canonic string representation of the y coordinate.

Method set: externvoidset(Gmp.mpz|intx, Gmp.mpz|inty)
variantvoidset(string(8bit)x, string(8bit)y)
Description: Set a new coordinate on the Crypto.ECC.Curve for the Point.
Note: Some curves (eg Crypto.ECC.Curve25519 do not support numeric coordinates); on the other hand the SECP curves prefer numeric coordinates.

Class __builtin.Nettle.Hash

Description

Base class for hash algorithms.

Implements common meta functions, such as key expansion algoritms and convenience functions.

Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

Inherit __Hash: inherit .__Hash : __Hash

Constant hmac_jwa_id: protected constantstring __builtin.Nettle.Hash.hmac_jwa_id
Description: JWS algorithm id (if any) for the HMAC sub-module. Overloaded by the actual implementations.

Method P_hash: string(8bit)P_hash(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: This is the Password-Based Key Derivation Function used in TLS.
Parameter password: The prf secret.
Parameter salt: The prf seed.
Parameter rounds: Ignored.
Parameter bytes: The number of bytes to generate.

Method `(): State res = __builtin.Nettle.Hash()()
Description: Calling `() will return a State object.

Method crypt_hash

string(7bit)crypt_hash(string(8bit)password, string(8bit)salt, int(0..)rounds)

Description

Password hashing function in Nettle.crypt_md5()-style.

Implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This is the algorithm used by crypt(2) in methods $5$ (SHA256) and $6$ (SHA512). See crypt_hash_pike() for details.

Note

In Pike 8.0.1876 and earlier this function generated incompatible hashes for passwords that had a length that was a power of 2. See crypt_hash_pike() for details.

See also

Nettle.crypt_md5(), crypt_hash_pike()

Method crypt_hash_pike

string(7bit)crypt_hash_pike(string(8bit)password, string(8bit)salt, int(0..)rounds)

Description

Password hashing function in Nettle.crypt_md5()-style.

Almost implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

This function is provided for compatibility with hashes generated by Pike 8.0.1876 and earlier.

It differs from crypt_hash() for passwords that have a length that is a power of 2 (phase 11).

Note

Do not use unless you know what you are doing!

See also

Nettle.crypt_md5(), crypt_hash()

Method crypt_pbkdf2

string(7bit)crypt_pbkdf2(string(8bit)password, string(7bit)salt, introunds)

Description

crypt()-style function using pbkdf2().

Compatible with PassLib and Phpass password hashing schemes "pbdkf2", "pbdkf2-sha256" and "pbdkf2-sha512".

Note

This function is provided for interoperability with password hashes provided from PassLib and/or Phpass. It is not recommended for use for new code, as this is not the indended use for the pbkdf2 algorithm.

See also

pbkdf2(), Crypto.Password.hash(), Crypto.Password.verify()

Method crypt_php

string(7bit)crypt_php(string(8bit)password, string(7bit)salt, int(0..)|voidrounds)

Description

Password hashing PHP Portable Hash-style.

Parameter password

Password to hash.

Parameter salt

7 bit string of length 8 or 9. The first character may encode the exponent for the number of rounds if rounds is 0.

Parameter rounds

Number of rounds. Defaults to taking the value from the salt if the salt has length 9, otherwise defaults to 1<<19.

This algorithm used with Crypto.MD5 is the one used for PHP Portable Hashes (aka "$P$" and "$H$").

Used with Crypto.SHA1 it should be compatible with hashes from Escher CMS (aka "$Q$").

Used with Crypto.SHA512 it should be compatible with hashes from Drupal (aka "$S$").

See also

crypt_hash(), Crypto.Password

Method eme_oaep_decode: string(8bit)|zeroeme_oaep_decode(string(8bit)message, string(8bit)|voidlabel, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: Decode an EME-OAEP encoded string.
Parameter message: Message to decode.
Parameter label: Label that was used when the message was encoded. Defaults to "".
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns the decoded message on success, and 0 (zero) on failure.
Note: The decoder attempts to take a constant amount of time on failure.
See also: eme_oaep_encode(), RFC 3447 section 7.1.2

Method eme_oaep_encode: string(8bit)|zeroeme_oaep_encode(string(8bit)message, int(1..)bytes, string(8bit)seed, string(8bit)|voidlabel, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the encoding algorithm used in RSAES-OAEP (RFC 3447 section 7.1.1).
Parameter message: Message to encode.
Parameter bytes: Number of bytes of destination encoding.
Parameter seed: A string of random bytes at least digest_size() long.
Parameter label: An optional encoding label. Defaults to "".
Parameter mgf: The mask generation function to use. Defaults to mgf1().
Returns: Returns the encoded string on success and 0 (zero) on failure (typically too few bytes to represent the result).
See also: eme_oaep_decode()

Method emsa_pss_encode: string(8bit)|zeroemsa_pss_encode(string(8bit)message, int(1..)bits, string(8bit)|voidsalt, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the signature digest algorithm used in RSASSA-PSS (RFC 3447 section 9.1.1).
Parameter message: Message to sign.
Parameter bits: Number of bits in result.
Parameter salt: Random string to salt the signature. Defaults to the empty string.
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns the signature digest on success and 0 (zero) on failure (typically too few bits to represent the result).
See also: emsa_pss_verify(), mgf1().

Method emsa_pss_verify: boolemsa_pss_verify(string(8bit)message, string(8bit)sign, int(1..)bits, int(0..)|voidsaltlen, function(string(8bit), int(0..):string(8bit))|voidmgf)
Description: This is the algorithm used to verify in RSASSA-PSS (RFC 3447 section 9.1.2).
Parameter message: Message that was signed.
Parameter sign: Signature digest to verify.
Parameter bits: Number of significant bits in sign.
Parameter saltlen: Length of the salt used.
Parameter mgf: Mask generation function to use. Defaults to mgf1().
Returns: Returns 1 on success and 0 (zero) on failure.
See also: emsa_pss_verify(), mgf1().

Method hash: string(8bit)hash(string(8bit)data)
Description: Works as a (possibly faster) shortcut for e.g. State(data)->digest(), where State is the hash state class corresponding to this Hash.
Parameter data: String to hash.
See also: Stdio.File, State()->update() and State()->digest().

Method hash

variantstring(8bit)hash(Stdio.File|Stdio.Buffer|String.Buffer|System.Memorysource, int(0..)|voidbytes)

Description

Works as a (possibly faster) shortcut for e.g. State( obj->read() )->digest(), where State is the hash state class corresponding to this Hash.

Parameter source

Object to read some data to hash from.

Parameter bytes

The number of bytes of the source object that should be hashed. Zero and negative values are ignored and the whole file is hashed. Support for negative values is deprecated.

Stdio.File, Stdio.Buffer, String.Buffer, System.Memory

Method hotp

inthotp(string(8bit)secret, intfactor, int(1..)|voidlength)

Description

HMAC-Based One-Time Password as defined by RFC 4226.

Can be used to implement the RFC 6238 Time-Based One-Time Password Algorithm by giving the factor (time()-T0)/X. Specifically for Google Authenticator this is Crypto.SHA1.hotp(secret,time()/30), using an 80 bit secret.

Parameter secret

A shared secret between both parties. Typically the same size as the hash output.

Parameter factor

A moving factor. Defined in RFC 4226 to be a counter synchronized between both parties.

Parameter length

The maximum number of digits of the one-time password. Defaults to 6. Note that the result is usually 0-padded to this length for user display purposes.

Method mgf1: string(8bit)mgf1(string(8bit)seed, int(0..)bytes)
Description: This is the mask generation function MFG1 from RFC 3447 appendix B.2.1.
Parameter seed: Seed from which the mask is to be generated.
Parameter bytes: Length of output.
Returns: Returns a pseudo-random string of length bytes.
Note: This function is compatible with the mask generation functions defined in PKCS #1, IEEE 1363-2000 and ANSI X9.44.

Method openssl_pbkdf

string(8bit)openssl_pbkdf(string(8bit)password, string(8bit)salt, introunds, intbytes)

Description

Password Based Key Derivation Function from OpenSSL.

This when used with Crypto.MD5 and a single round is the function used to derive the key to encrypt Standards.PEM body data.

FIXME

Derived from OpenSSL. Is there any proper specification?

It seems to be related to PBKDF1 from RFC 2898.

See also

pbkdf1(), pbkdf2(), crypt_hash()

Method pbkdf1: string(8bit)pbkdf1(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: Password Based Key Derivation Function #1 from RFC 2898. This method is compatible with the one from PKCS#5 v1.5.
Parameter password
Parameter salt: Password and salt for the keygenerator.
Parameter rounds: The number of iterations to rehash the input.
Parameter bytes: The number of bytes of output. Note that this has an upper limit of the size of a single digest.
Returns: Returns the derived key.
Note: RFC 2898 does not recommend this function for anything else than compatibility with existing applications, due to the limits in the length of the generated keys.
See also: HKDF, pbkdf2(), openssl_pbkdf(), crypt_hash()

Method pbkdf2: string(8bit)pbkdf2(string(8bit)password, string(8bit)salt, introunds, intbytes)
Description: Password Based Key Derivation Function #2 from RFC 2898, PKCS#5 v2.0.
Parameter password
Parameter salt: Password and salt for the keygenerator.
Parameter rounds: The number of iterations to rehash the input.
Parameter bytes: The number of bytes of output.
Returns: Returns the derived key.
See also: HKDF, pbkdf1(), openssl_pbkdf(), crypt_hash()

Method pkcs_digest: string(8bit)pkcs_digest(object|string(8bit)s)
Description: Make a PKCS-1 digest info block with the message s.
See also: Standards.PKCS.Signature.build_digestinfo()

Class __builtin.Nettle.Hash.HKDF

Description: HMAC-based Extract-and-Expand Key Derivation Function, HKDF, RFC 5869. This is very similar to pbkdf2, with a few important differences. HKDF can use an "info" string that binds a generated password to a specific use or application (e.g. port number or cipher suite). It does not however support multiple rounds of hashing to add computational cost to brute force attacks.

Method create: __builtin.Nettle.Hash.HKDF__builtin.Nettle.Hash.HKDF(string(8bit)password, string(8bit)|voidsalt)
Description: Initializes the HKDF object with a RFC 5869 2.2 HKDF-Extract(salt, IKM) call.

Method expand: string(8bit)expand(string(8bit)info, intbytes)
Description: This is similar to the RFC 5869 2.3 HKDF-Expand(PRK, info, L) function, but PRK is taken from the object.

Method extract: string(8bit)extract(string(8bit)password)
Description: This is similar to the RFC 5869 2.2 HKDF-Extract(salt, IKM) function, but the salt is the previously generated PRK.

Class __builtin.Nettle.Hash.SCRAM

Description

SCRAM, defined by RFC 5802.

This implements both the client- and the serverside. You normally run either the server or the client, but if you would run both (use a separate client and a separate server object!), the sequence would be:

client_1 -> server_1 -> server_2 -> client_2 -> server_3 -> client_3

Note

If you are a client, you must use the client_* methods; if you are a server, you must use the server_* methods. You cannot mix both client and server methods in a single object.

Note

This implementation does not pretend to support the full protocol. Most notably optional extension arguments are not supported (yet).

See also

client_1, server_1

Method client_1: string(7bit)client_1(void|stringusername)
Description: Client-side step 1 in the SCRAM handshake.
Parameter username: The username to feed to the server. Some servers already received the username through an alternate channel (usually during the hash-function selection handshake), in which case it should be omitted here.
Returns: The client-first request to send to the server.
See also: client_2

Method client_2: string(7bit)|zeroclient_2(string(8bit)line, stringpass)
Description: Client-side step 2 in the SCRAM handshake.
Parameter line: The received server-first challenge from the server.
Parameter pass: The password to feed to the server.
Returns: The client-final response to send to the server. If the response is null, the server sent something unacceptable or unparseable.
See also: client_3

Method client_3: boolclient_3(string(8bit)line)
Description: Final client-side step in the SCRAM handshake. If we get this far, the server has already verified that we supplied the correct credentials. If this step fails, it means the server does not have our credentials at all and is an imposter.
Parameter line: The received server-final verification response.
Returns: True if the server is valid, false if the server is invalid.

Method server_1: string|zeroserver_1(string(8bit)line)
Description: Server-side step 1 in the SCRAM handshake.
Parameter line: The received client-first request from the client.
Returns: The username specified by the client. Returns null if the response could not be parsed.
See also: server_2

Method server_2: string(7bit)server_2(string(8bit)salt, intiters)
Description: Server-side step 2 in the SCRAM handshake.
Parameter salt: The salt corresponding to the username that has been specified earlier.
Parameter iters: The number of iterations the hashing algorithm should perform to compute the authentication hash.
Returns: The server-first challenge to send to the client.
See also: server_3

Method server_3: string(7bit)|zeroserver_3(string(8bit)line, string(8bit)salted_password)
Description: Final server-side step in the SCRAM handshake.
Parameter line: The received client-final challenge and response from the client.
Parameter salted_password: The salted (using the salt provided earlier) password belonging to the specified username.
Returns: The server-final response to send to the client. If the response is null, the client did not supply the correct credentials or the response was unparseable.

Module __builtin.Nettle.Hash.HMAC

Description

HMAC (Hashing for Message Authenticity Control) for the hash algorithm. Typically used as e.g. Crypto.SHA256.HMAC(key)(data) or Crypto.SHA256.HMAC(key)->update(data)->update(more_data)->digest().

RFC 2104.

See also

Crypto.HMAC

Inherit MAC: inherit .MAC : MAC

Method `(): State res = __builtin.Nettle.Hash()()
Description: Returns a new State object initialized with a password, and optionally block size b. Block size defaults to the hash function block size.

Method iv_size: int(0)iv_size()
Description: HMAC has no modifiable iv.

Method jwa: string(7bit)jwa()
Description: JWS algorithm identifier (if any, otherwise 0).
See also: RFC 7518 section 3.1

Method key_size: int(0..)key_size()
Description: Returns the block size of the encapsulated hash.
Note: Other key sizes are allowed, and will be expanded/compressed to this size.

Class __builtin.Nettle.Hash.HMAC.State

Description: The HMAC hash state.

Inherit this_program: inherit ::this_program : this_program

Method `()

string(8bit) res = __builtin.Nettle.Hash.HMAC.State()()

Description

Hashes the text according to the HMAC algorithm and returns the hash value.

This works as a combined update() and digest().

Method create: __builtin.Nettle.Hash.HMAC.State__builtin.Nettle.Hash.HMAC.State(string(8bit)passwd, int(1..)|voidb)
Parameter passwd: The secret password (K).
Parameter b: Block size. Must be larger than or equal to the digest_size(). Defaults to the block_size().

Method digest: stringdigest(int(0..)|voidlength)
Description: Generate the digest for the current state.

Method digest_info: string(8bit)digest_info(string(8bit)text)
Description: Hashes the text according to the HMAC algorithm and returns the hash value as a PKCS-1 digestinfo block.

Method jwk: mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_key)
Description: Generate a JWK-style mapping of the object.
Parameter private_key: Ignored.
Returns: Returns a JWK-style mapping on success, and 0 (zero) on failure.
See also: create(), Web.encode_jwk(), RFC 7517 section 4, RFC 7518 section 6.4

Method set_iv: this_programset_iv(string(8bit)iv)
Description: HMAC does not have a modifiable iv.

Method update: this_programupdate(string(8bit)data)
Description: Update state with data.

Class __builtin.Nettle.MAC

Description

Base class for Message Authentication Codes (MAC)s.

These are hashes that have been extended with a secret key.

Inherit __Hash: inherit .__Hash : __Hash

Constant mac_jwa_id: protected constantstring __builtin.Nettle.MAC.mac_jwa_id
Description: JWS algorithm id (if any). Overloaded by the actual implementations.
Note: Never access this value directly. Use jwa().
See also: jwa()

Method iv_size

int(0..)iv_size()

Description

Returns the size of the iv/nonce (if any).

Some MACs like eg Crypto.SHA1.HMAC have fixed ivs, in which case this function will return 0.

Method jwa: string(7bit)jwa()
Description: JWS algorithm identifier (if any, otherwise 0).
See also: RFC 7518 section 3.1

Method key_size: int(0..)key_size()
Description: Returns the recomended size of the key.

Class __builtin.Nettle.MAC.State

Description: The state for the MAC.

Inherit this_program: inherit ::this_program : this_program

Method create: __builtin.Nettle.MAC.State__builtin.Nettle.MAC.State(stringkey)
Parameter key: The secret key for the hash.

Method iv_size

int(0..)iv_size()

Description

Returns the size of the iv/nonce (if any).

Some MACs like eg Crypto.SHA1.HMAC have fixed ivs, in which case this function will return 0.

Method jose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_decode(string(7bit)jws)

Description

Verify and decode a JOSE JWS MAC signed value.

Parameter jws

A JSON Web Signature as returned by jose_sign().

Returns

Returns 0 (zero) on failure, and an array

Array
`mapping(string(7bit):string(7bit)\|int) 0`	The JOSE header.
`string(8bit)1`	The signed message.

on success.

See also

jose_sign(), RFC 7515 section 3.5

Method jose_sign: string(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders)
Description: Signs the message with a JOSE JWS MAC signature.
Parameter message: Message to sign.
Parameter headers: JOSE headers to use. Typically a mapping with a single element "typ".
Returns: Returns the signature on success, and 0 (zero) on failure (typically that JOSE doesn't support this MAC).
See also: jose_decode(), RFC 7515

Method key_size: int(0..)key_size()
Description: Returns the recomended size of the key.

Class __builtin.Nettle.Sign

Description

Base class for cryptographic signature algorithms.

Typical classes implementing this API are Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA.

Method _equal

boolequal(__builtin.Nettle.Signfrom, mixedx)

Description

Check whether two objects are equivalent.

This includes checking both the public and private keys.

See also

public_key_equal()

Method jose_decode

array(mapping(string(7bit):string(7bit)|int)|string(8bit))|zerojose_decode(string(7bit)jws)

Description

Verify and decode a JOSE JWS signed value.

Parameter jws

A JSON Web Signature as returned by jose_sign().

Returns

Returns 0 (zero) on failure, and an array

Array
`mapping(string(7bit):string(7bit)\|int) 0`	The JOSE header.
`string(8bit)1`	The signed message.

Note

The default implementation returns 0 for all parameters, and can thus serve as a fallback for signature algorithms that don't support or aren't supported by JWS (eg Crypto.DSA).

See also

jose_sign(), pkcs_verify(), RFC 7515

Method jose_sign: string(7bit)|zerojose_sign(string(8bit)message, mapping(string(7bit):string(7bit)|int)|voidheaders, .Hash|voidh)
Description: Signs the message with a JOSE JWS signature using hash algorithm h and JOSE headers headers.
Parameter message: Message to sign.
Parameter headers: JOSE headers to use. Typically a mapping with a single element "typ".
Parameter h: Hash algorithm to use. Valid hashes depend on the signature algorithm. The default value depends on the signature algorithm.
Returns: Returns the signature on success, and 0 (zero) on failure (typically that either the hash algorithm is invalid for this signature algorithm),
Note: The default implementation returns 0 for all parameters, and can thus serve as a fallback for signature algorithms that don't support or aren't supported by JWS (eg Crypto.DSA).
See also: jose_decode(), pkcs_sign(), RFC 7515

Method jwk: mapping(string(7bit):string(7bit))|zerojwk(bool|voidprivate_key)
Description: Generate a JOSE JWK mapping representation of the object.
Parameter private_key: If true, include private fields in the result.
Returns: Returns a mapping as per RFC 7517 section 4 on success, and 0 (zero) on failure (typically that the object isn't initialized properly, or that it isn't supported by JWK).
See also: Web.encode_jwk(), Web.decode_jwk(), RFC 7517 section 4

Method jwk_thumbprint

string(8bit)|zerojwk_thumbprint(.Hashh)

Description

Generate a JOSE JWK Thumbprint of the object.

Parameter h

Hash algorithm to use.

Returns

Returns the thumbprint (ie hash of the public fields) on success, and 0 (zero) on failure (typically that the object isn't initialized properly, or that it isn't supported by JWK).

A typical use for this function is to generate a kid (key ID) value (cf RFC 7638 section 1.

See also

jwk(), RFC 7638

Method key_size: int(0..)key_size()
Description: Returns the number of bits in the private key.

Method name: string(7bit)name()
Description: Returns the printable name of the signing algorithm.

Method pkcs_algorithm_identifier: Sequence|zeropkcs_algorithm_identifier()
Description: Returns the PKCS-1 AlgorithmIdentifier.

Method pkcs_public_key: Sequencepkcs_public_key()
Description: Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

Method pkcs_sign: string(8bit)pkcs_sign(string(8bit)message, .Hashh)
Description: Signs the message with a PKCS-1 signature using hash algorithm h.

Method pkcs_signature_algorithm_id: Sequence|zeropkcs_signature_algorithm_id(.Hashhash)
Description: Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.

Method pkcs_verify: boolpkcs_verify(string(8bit)message, .Hashh, string(8bit)sign)
Description: Verify PKCS-1 signature sign of message message using hash algorithm h.

Method public_key_equal: boolpublic_key_equal(this_programother)
Description: Check whether the public key is the same in two objects.
Note: This function differs from _equal() in that only the public key is regarded, and that it only needs to regard objects implementing Crypto.Sign.
See also: _equal()

Class __builtin.Nettle.__Hash

Description

Base class for hash algorithms.

Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

Method block_size: int(1..)block_size()
Description: Returns the internal block size of the hash algorithm.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Class __builtin.Nettle.__Hash.State

Description

This is the context for a single incrementally updated hash.

Most of the functions here are only prototypes, and need to be overrided via inherit.

Method block_size: int(1..)block_size()
Description: Returns the internal block size of the hash algorithm.

Method create

__builtin.Nettle.__Hash.State__builtin.Nettle.__Hash.State(string(8bit)|voiddata)

Description

Create the new context, and optionally add some initial data to hash.

The default implementation calls update() with data if any, so there's usually no reason to override this function, since overriding update() should be sufficient.

Method digest: string(8bit)digest(int|voidlength)
Description: Generates a digest, and resets the hashing contents.
Parameter length: If the length argument is provided, the digest is truncated to the given length.
Returns: The digest.

Method digest_size: int(0..)digest_size()
Description: Returns the size of a hash digest.

Method init: this_programinit(string(8bit)|voiddata)
Description: Reset the context, and optionally add some initial data to the hash.

Method name: string(7bit)name()
Description: Returns a human readable name for the algorithm.

Method update: this_programupdate(string(8bit)data)
Description: Add some more data to hash.

Module __builtin.Sql

Description: Generic base classes for the Sql interfaces.

Constant QUERY_OPTION_CHARSET: constantstring __builtin.Sql.QUERY_OPTION_CHARSET
Description: Field to set in the query bindings mapping to set a character set for just the current query. Only supported by some databases.

Variable zero_arg: ZeroWrapper __builtin.Sql.zero_arg
Description: Instance of ZeroWrapper used by Connection()->handle_extraargs().

Class __builtin.Sql.FutureResult

Description: The promise result class; it will contain the results of a query.
See also: Promise, Connection.promise_query()

Variable affected_rows: finalint __builtin.Sql.FutureResult.affected_rows
Description: The number of affected rows.

Variable bindings: finalmapping(string:mixed)|zero __builtin.Sql.FutureResult.bindings
Description: The parameter bindings belonging to the query.

Variable data: finalarray(mixed)|zero __builtin.Sql.FutureResult.data
Description: The returned raw unadorned records, all typed data. Once get() has been accessed, data will point to the same adorned records.
See also: Sql.Connection->big_typed_query()

Variable fields: finalarray(mapping(string:mixed))|zero __builtin.Sql.FutureResult.fields
Description: The description of the fields in a record.

Variable query: finalstring|zero __builtin.Sql.FutureResult.query
Description: The SQL query.

Variable status_command_complete: finalstring|mixed __builtin.Sql.FutureResult.status_command_complete
Description: The status of the completed command. If the command is still in progress, the value is null. If an error has occurred, it contains the backtrace of that error.

Method get: finalarray(mapping(string:mixed)) get()
Returns: The returned labeled records, all typed data.
See also: Sql.Connection->query(), data

Class __builtin.Sql.Promise

Description: This class is the base class for promise based SQL queries. future() will return a future which carries FutureResult objects to contain the result of the query.
See also: FutureResult, Connection.promise_query()

Inherit Promise: inherit Concurrent.Promise : Promise

Method discard_records: finalthis_programdiscard_records(int(-1..)over)
Parameter over: Discard any records over this number. -1 means do not discard any records (default).

Method max_records: finalthis_programmax_records(int(-1..)max)
Parameter max: If the query returns more than this number of records, fail the future. -1 means no maximum (default).

Method min_records: finalthis_programmin_records(int(0..)min)
Parameter min: If the query returns less than this number of records, fail the future. Defaults to 0.

Class __builtin.Sql.ZeroWrapper

Description: Wrapper to handle conversion of zero to NULL in Connection()->handle_extraargs().
See also: zero

Method _sprintf

stringsprintf(stringformat, ... __builtin.Sql.ZeroWrapperarg ... )

Returns

Returns the following:

`"NULL"`	If `fmt` is `'s'`.
`"ZeroWrapper()"`	If `fmt` is `'O'`.

Otherwise it formats a 0 (zero).

Module _static_modules

Module _static_modules.Builtin

Class _static_modules.Builtin.Future (< ValueType >)

Description: Prototype class for Concurrent.Future.
See also: Concurrent.Future, Promise

Generic ValueType: __generic__mixedValueType = mixed

Method delay: Future(< ValueType >) delay(int|floatseconds)

Method filter: Future(< ValueType >) filter(function(ValueType, __unknown__ ... :bool) fun, mixed ... extra)

Method get: ValueTypeget()

Method get: zero|ValueTypeget()

Method get_backend: Pike.Backendget_backend()

Method map: Future(< mixed >) map(function(ValueType, __unknown__ ... :mixed) fun, mixed ... extra)

Method map_with: Future(< mixed >) map_with(function(ValueType, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method on_await: Future(< ValueType >) on_await(function(mixed, function(mixed, __unknown__ ... :void)|void:void) cb)

Method on_failure: Future(< ValueType >) on_failure(function(mixed, __unknown__ ... :void) cb, mixed ... extra)

Method on_success: Future(< ValueType >) on_success(function(ValueType, __unknown__ ... :void) cb, mixed ... extra)

Method promise_factory: Promisepromise_factory()

Method query_failure_callbacks: array(function(mixed, __unknown__ ... :void)) query_failure_callbacks()

Method query_success_callbacks: array(function(ValueType, __unknown__ ... :void)) query_success_callbacks()

Method recover: Future(< mixed >) recover(function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Method recover_with: Future(< mixed >) recover_with(function(mixed, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method set_backend: voidset_backend(Pike.Backendbackend)

Method then: Future(< mixed >) then(function(ValueType, __unknown__ ... :mixed)|voidonfullfillment, function(mixed, __unknown__ ... :mixed)|voidonrejected, mixed ... extra)

Method thencatch: Future(< mixed >) thencatch(function(mixed, __unknown__ ... :mixed) onrejected, mixed ... extra)

Method timeout: Future(< ValueType >) timeout(int|floatseconds)

Method transform: Future(< mixed >) transform(function(ValueType, __unknown__ ... :Future(< mixed >)) fun, function(mixed, __unknown__ ... :Future(< mixed >)) fun, mixed ... extra)

Method transform: Future(< mixed >) transform(function(ValueType, __unknown__ ... :mixed) fun, function(mixed, __unknown__ ... :mixed) fun, mixed ... extra)

Method wait: Future(< ValueType >) wait()

Method zip: array(Future(< mixed >)) zip(array(Future(< mixed >)) others)
array(Future(< mixed >)) zip(Future(< mixed >) ... others)

Class _static_modules.Builtin.Promise (< ValueType >)

Description: Prototype class for Concurrent.Promise.
See also: Concurrent.Promise, Future

Generic ValueType: __generic__mixedValueType = mixed

Inherit Future: inherit Future(< ValueType >) : Future

Method failure: Promise(< ValueType >) failure(mixedvalue, int|voidtry)

Method future: Future(< ValueType >) future()

Method success: Promise(< ValueType >) success(ValueTypevalue, int|voidtry)

Method try_failure: Promise(< ValueType >) try_failure(mixedvalue)

Method try_success: Promise(< ValueType >) try_success(ValueTypevalue)

Module _static_modules._math

Description: This module does not contain any public symbols.

Module _static_modules._system

Description: Low-level module that embodies common operating system calls, making them available to the Pike programmer.
Note: You typically do not want to access this module directly. Use the System module instead.
See also: System

Constant CPU_TIME_IMPLEMENTATION: constantstring _static_modules._system.CPU_TIME_IMPLEMENTATION
Description: This string constant identifies the internal interface used to get the CPU time. It is an implementation detail - see rusage.c for possible values and their meanings.
See also: gethrvtime, gauge

Constant CPU_TIME_IS_THREAD_LOCAL: constantstring _static_modules._system.CPU_TIME_IS_THREAD_LOCAL
Description: This string constant tells whether or not the CPU time, returned by e.g. gethrvtime, is thread local or not. The value is "yes" if it is and "no" if it isn't. The value is also "no" if there is no thread support.
See also: gethrvtime, gauge

Constant CPU_TIME_RESOLUTION: constantint _static_modules._system.CPU_TIME_RESOLUTION
Description: The resolution of the CPU time, returned by e.g. gethrvtime, in nanoseconds. It is -1 if the resolution isn't known.
See also: gethrvtime, gauge

Constant ITIMER_PROF: constant _static_modules._system.ITIMER_PROF
Description: Identifier for a timer that decrements both when the process is executing and when the system is executing on behalf of the process.
See also: setitimer, getitimer

Constant ITIMER_REAL: constant _static_modules._system.ITIMER_REAL
Description: Identifier for a timer that decrements in real time.
See also: setitimer, getitimer

Constant ITIMER_VIRTUAL: constant _static_modules._system.ITIMER_VIRTUAL
Description: Identifier for a timer that decrements only when the process is executing.
See also: setitimer, getitimer

Constant REAL_TIME_IMPLEMENTATION: constantstring _static_modules._system.REAL_TIME_IMPLEMENTATION
Description: This string constant identifies the internal interface used to get the high resolution real time. It is an implementation detail - see rusage.c for possible values and their meanings.
See also: gethrtime

Constant REAL_TIME_IS_MONOTONIC

constantstring _static_modules._system.REAL_TIME_IS_MONOTONIC

Description

This string constant tells whether or not the high resolution real time returned by gethrtime, is monotonic or not. The value is "yes" if it is and "no" if it isn't.

Monotonic time is not affected by clock adjustments that might happen to keep the calendaric clock in synch. It's therefore more suited to measure time intervals in programs.

See also

gethrtime

Constant REAL_TIME_RESOLUTION: constantint _static_modules._system.REAL_TIME_RESOLUTION
Description: The resolution of the real time returned by gethrtime, in nanoseconds. It is -1 if the resolution isn't known.
See also: gethrtime

Method chmod: voidchmod(stringpath, intmode)
Description: Sets the protection mode of the specified path.
Note: Throws errors on failure.
See also: Stdio.File->open(), errno()

Method chown

voidchown(stringpath, intuid, intgid, void|intsymlink)

Description

Sets the owner and group of the specified path.

If symlink is set and path refers to a symlink, then the owner and group for the symlink are set. Symlinks are dereferenced otherwise.

Note

Throws errors on failure.

This function is not available on all platforms. On some platforms the symlink flag isn't supported. In that case, the function does nothing if path is a symlink.

Method chroot

intchroot(stringnewroot)
intchroot(Stdio.Filenewroot)

Description

Changes the root directory for this process to the indicated directory.

Returns

A nonzero value is returned if the call is successful. If there's an error then zero is returned and errno is set appropriately.

Note

Since this function modifies the directory structure as seen from Pike, you have to modify the environment variables PIKE_MODULE_PATH and PIKE_INCLUDE_PATH to compensate for the new root-directory.

This function only exists on systems that have the chroot(2) system call.

The second variant only works on systems that also have the fchroot(2) system call.

Note

On success the current working directory will be changed to the new "/". This behavior was added in Pike 7.9.

Note

This function could be interrupted by signals prior to Pike 7.9.

Method cleargroups

voidcleargroups()

Description

Clear the supplemental group access list.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setgroups(), initgroups(), getgroups()

Method clonefile: voidclonefile(string(8bit)from, string(8bit)to)
Description: Copy a file from with copy-on-write semantics to the destination named to.
Note: This function is currently only available on macOS and Linux, and then only when from and to reference a common file system with copy-on-write support (e.g. an APFS volume).
See also: hardlink(), symlink()

Method daemon: intdaemon(intnochdir, intnoclose)
Description: Low level system daemon() function, see also Process.daemon()

Method dumpable

booldumpable(bool|voidval)

Description

Get and/or set whether this process should be able to dump core.

Parameter val

Optional argument to set the core dumping state.

`0`	Disable core dumping for this process.
`1`	Enable core dumping for this process.

Returns

Returns 1 if this process currently is capable of dumping core, and 0 (zero) if not.

Note

This function is currently only available on some versions of Linux.

Method get_netinfo_property

array(string) get_netinfo_property(stringdomain, stringpath, stringproperty)

Description

Queries a NetInfo server for property values at the given path.

Parameter domain

NetInfo domain. Use "." for the local domain.

Parameter path

NetInfo path for the property.

Parameter property

Name of the property to return.

Returns

An array holding all property values. If the path or property cannot be not found 0 is returned instead. If the NetInfo domain is not found or cannot be queried an exception is thrown.

Example

system.get_netinfo_property(".", "/locations/resolver", "domain");
   ({
      "idonex.se"
   })

Note

Only available on operating systems which have NetInfo libraries installed.

Method getegid: intgetegid()
Description: Get the effective group ID.
See also: setuid, getuid, setgid, getgid, seteuid, geteuid, setegid

Method geteuid: intgeteuid()
Description: Get the effective user ID.
See also: setuid, getuid, setgid, getgid, seteuid, getegid, setegid

Method getgid: intgetgid()
Description: Get the real group ID.
See also: setuid, getuid, setgid, seteuid, geteuid, getegid, setegid

Method getgroups

array(int) getgroups()

Description

Get the current supplemental group access list for this process.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setgroups(), cleargroups(), initgroups(), getgid(), getgid(), getegid(), setegid()

Method gethostbyaddr: array(string|array(string)) gethostbyaddr(stringaddr)
Description: Returns an array with information about the specified IP address.
Returns: The returned array contains the same information as that returned by gethostbyname().
Note: This function only exists on systems that have the gethostbyaddr(2) or similar system call.
See also: gethostbyname()

Method gethostbyname

array(string|array(string)) gethostbyname(stringhostname)

Description

Returns an array with information about the specified host.

Returns

The returned array contains the following:

Array
`stringhostname`	Name of the host.
`array(string) ips`	Array of IP numbers for the host.
`array(string) aliases`	Array of alternative names for the host.

Note

This function only exists on systems that have the gethostbyname(2) or similar system call.

See also

gethostbyaddr()

Method gethostname: stringgethostname()
Description: Returns a string with the name of the host.
Note: This function only exists on systems that have the gethostname(2) or uname(2) system calls.

Method getitimer

array(float) getitimer(inttimer)

Description

Shows the state of the selected timer.

Returns

Array
`float0`	The interval of the timer.
`float1`	The value of the timer.

Parameter timer

One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Method getloadavg

array(float) getloadavg()

Description

Get system load averages.

Returns

Array
`float0`	Load average over the last minute.
`float1`	Load average over the last 5 minutes.
`float2`	Load average over the last 15 minutes.

Method getpgrp

intgetpgrp(int|voidpid)

Description

Get the process group id for the process pid. With no argguments or with 'pid' equal to zero, returns the process group ID of this process.

Note

Not all platforms support getting the process group for other processes.

Not supported on all platforms.

See also

getpid, getppid

Method getpid: intgetpid()
Description: Returns the process ID of this process.
See also: getppid, getpgrp

Method getppid: intgetppid()
Description: Returns the process ID of the parent process.
See also: getpid, getpgrp

Method getrlimit

array(int) getrlimit(stringresource)

Description

Returns the current process limitation for the selected resource.

Parameter resource

`cpu`	The CPU time limit in seconds.
`fsize`	The maximum size of files the process may create.
`data`	The maximum size of the process's data segment.
`stack`	The maximum size of process stack, in bytes.
`core`
`rss`	Specifies the limit of pages the process's resident set.
`nproc`	The maximum number of processes that can be created for the real user ID of the calling process.
`nofile`	The maximum number of file descriptors the process can open, +1.
`memlock`	The maximum number of bytes of virtual memory that may be locked into RAM.
`as`
`vmem`

Returns

Array
`int0`	The soft limit for the resource. `-1` means no limit.
`int1`	The hard limit for the resource. `-1` means no limit.

Note

This function nor all the resources are available on all systems.

See also

getrlimits, setrlimit

Method getrlimits: mapping(string:array(int)) getrlimits()
Description: Returns all process limits in a mapping.
See also: getrlimit, setrlimit

Method getrusage

mapping(string:int) getrusage()

Description

Return resource usage about the current process. An error is thrown if it isn't supported or if the system fails to return any information.

Returns

Returns a mapping describing the current resource usage:

`"utime" : int`	Time in milliseconds spent in user code.
`"stime" : int`	Time in milliseconds spent in system calls.
`"maxrss" : int`	Maximum used resident size in kilobytes. [1]
`"ixrss" : int`	Quote from GNU libc: An integral value expressed in kilobytes times ticks of execution, which indicates the amount of memory used by text that was shared with other processes. [1]
`"idrss" : int`	Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for data. [1]
`"isrss" : int`	Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for stack space. [1]
`"minflt" : int`	Minor page faults, i.e. TLB misses which required no disk I/O.
`"majflt" : int`	Major page faults, i.e. paging with disk I/O required.
`"nswap" : int`	Number of times the process has been swapped out entirely.
`"inblock" : int`	Number of block input operations.
`"oublock" : int`	Number of block output operations.
`"msgsnd" : int`	Number of IPC messsages sent.
`"msgrcv" : int`	Number of IPC messsages received.
`"nsignals" : int`	Number of signals received.
`"nvcsw" : int`	Number of voluntary context switches (usually to wait for some service).
`"nivcsw" : int`	Number of preemptions, i.e. context switches due to expired time slices, or when processes with higher priority were scheduled.
`"sysc" : int`	Number of system calls. [2]
`"ioch" : int`	Number of characters read and written. [2]
`"rtime" : int`	Elapsed real time (ms). [2]
`"ttime" : int`	Elapsed system trap (system call) time (ms). [2]
`"tftime" : int`	Text page fault sleep time (ms). [2]
`"dftime" : int`	Data page fault sleep time (ms). [2]
`"kftime" : int`	Kernel page fault sleep time (ms). [2]
`"ltime" : int`	User lock wait sleep time (ms). [2]
`"slptime" : int`	Other sleep time (ms). [2]
`"wtime" : int`	Wait CPU (latency) time (ms). [2]
`"stoptime" : int`	Time spent in stopped (suspended) state. [2]
`"brksize" : int`	Heap size. [3]
`"stksize" : int`	Stack size. [3]

Note

[1] Not if /proc rusage is used.

[2] Only from (Solaris?) /proc rusage.

[3] Only from /proc PRS usage.

On some systems, only utime will be filled in.

See also

gethrvtime()

Method getsid: intgetsid(int|voidpid)
Description: Get the process session ID for the given process. If pid is not specified, the session ID for the current process will be returned.
Note: This function is not available on all platforms.
Throws: Throws an error if the system call fails.
See also: getpid, getpgrp, setsid

Method gettimeofday: array(int) gettimeofday()
Description: Calls gettimeofday(); the result is an array of seconds, microseconds, and possible tz_minuteswes, tz_dstttime as given by the gettimeofday(2) system call (read the man page).
See also: time(), gethrtime()

Method getuid: intgetuid()
Description: Get the real user ID.
See also: setuid, setgid, getgid, seteuid, geteuid, setegid, getegid

Method hardlink: voidhardlink(string(8bit)from, string(8bit)to)
Description: Create a hardlink named to from the file from.
Note: This function is not available on all platforms.
See also: symlink(), clonefile(), mv(), rm()

Method hw_random: string(8bit)hw_random(int(0..)length)
Description: Read a specified number of bytes from the hardware random generator, if available. This function will not exist if hardware random is not available. Currently only supports Intel RDRAND CPU instruction.

Method initgroups

voidinitgroups(stringname, intbase_gid)

Description

Initializes the supplemental group access list according to the system group database. base_gid is also added to the group access list.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setuid(), getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid(), getgroups(), setgroups()

Method innetgr: boolinnetgr(stringnetgroup, string|voidmachine, string|voiduser, string|voiddomain)
Description: Searches for matching entries in the netgroup database (usually /etc/netgroup). If any of the machine, user or domain arguments are zero or missing, those fields will match any value in the selected netgroup.
Note: This function isn't available on all platforms.

Method nanosleep

floatnanosleep(int|floatseconds)

Description

Call the system nanosleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

Returns the remaining time to sleep (as the system function does).

See also

predef::sleep()sleep()usleep()

Note

May not be present; only exists if the function exists in the current system.

Method rdtsc: intrdtsc()
Description: Executes the rdtsc (clock pulse counter) instruction and returns the result.

Method readlink: string(8bit)readlink(string(8bit)path)
Description: Returns what the symbolic link path points to.
Note: This function is not available on all platforms.
See also: symlink()

Method resolvepath

string(8bit)resolvepath(string(8bit)path)

Description

Resolve all symbolic links of a pathname.

This function resolves all symbolic links, extra ``/'' characters and references to /./ and /../ in path, and returns the resulting absolute path, or 0 (zero) if an error occurs.

Note

This function is not available on all platforms.

See also

readlink(), symlink()

Method setegid: intsetegid(integid)
Description: Set the effective group ID to egid. If egid is -1 the uid for "nobody" will be used.
Returns: Returns the current errno.
Throws: Throws an error if there is no "nobody" user when egid is -1.
Note: This function isn't available on all platforms.

Method seteuid: intseteuid(inteuid)
Description: Set the effective user ID to euid. If euid is -1 the uid for "nobody" will be used.
Returns: Returns the current errno.
Throws: Throws an error if there is no "nobody" user when euid is -1.
Note: This function isn't available on all platforms.

Method setgid: intsetgid(intgid)
Description: Sets the real group ID, effective group ID and saved group ID to gid. If gid is -1 the uid for "nobody" will be used.
Throws: Throws an error if no "nobody" user when gid is -1.
Returns: Returns the current errno.
Note: This function is not available on all platforms.
See also: getuid(), setuid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Method setgroups

voidsetgroups(array(int) gids)

Description

Set the supplemental group access list for this process.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

initgroups(), cleargroups(), getgroups(), getgid(), getgid(), getegid(), setegid()

Method setitimer: floatsetitimer(inttimer, int|floatvalue)
Description: Sets the timer to the supplied value. Returns the current timer interval.
Parameter timer: One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Method setpgrp: intsetpgrp()
Description: Make this process a process group leader.
Note: Not supported on all platforms.

Method setproctitle: voidsetproctitle(stringtitle, mixed ... extra)
Description: Sets the processes title.

Method setresgid: intsetresgid(intrgid, integid, intsgid)
Description: Sets the real, effective and saved group ID to rgid, egid and sgid respectively.
Returns: Returns zero on success and errno on failure.

Method setresuid: intsetresuid(intruid, inteuid, intsuid)
Description: Sets the real, effective and saved set-user-ID to ruid, euid and suid respectively.
Returns: Returns zero on success and errno on failure.

Method setrlimit: boolsetrlimit(stringresource, intsoft, inthard)
Description: Sets the soft and the hard process limit on a resource.
See also: getrlimit, getrlimits

Method setsid: intsetsid()
Description: Set a new process session ID for the current process, and return it.
Note: This function isn't available on all platforms.
Throws: Throws an error if the system call fails.
See also: getpid, setpgrp, getsid

Method setuid: intsetuid(intuid)
Description: Sets the real user ID, effective user ID and saved user ID to uid.
Returns: Returns the current errno.
Note: This function isn't available on all platforms.
See also: getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Method sleep

intsleep(intseconds)

Description

Call the system sleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

Note

The system's sleep function often utilizes the alarm(2) call and might not be perfectly thread safe in combination with simultaneous sleep()'s or alarm()'s. It might also be interrupted by other signals.

If you don't need it to be independant of the system clock, use predef::sleep() instead.

May not be present; only exists if the function exists in the current system.

See also

predef::sleep()usleep()nanosleep()

Method symlink: voidsymlink(string(8bit)from, string(8bit)to)
Description: Create a symbolic link named to that points to from.
Note: This function is not available on all platforms.
See also: hardlink(), readlink(), clonefile(), mv(), rm()

Method sync: voidsync()
Description: Flush operating system disk buffers to permanent storage.
Note: On some operating systems this may require administrative privileges.

Method umask

intumask(void|intmask)

Description

Set the current umask to mask.

If mask is not specified the current umask will not be changed.

Returns

Returns the old umask setting.

Method uname

mapping(string:string) uname()

Description

Get operating system information.

Returns

The resulting mapping contains the following fields:

`"sysname" : string`	Operating system name.
`"nodename" : string`	Hostname.
`"release" : string`	Operating system release.
`"version" : string`	Operating system version.
`"machine" : string`	Hardware architecture.
`"architecture" : string`	Basic instruction set architecture.
`"isalist" : string`	List of upported instruction set architectures. Usually space-separated.
`"platform" : string`	Specific model of hardware.
`"hw provider" : string`	Manufacturer of the hardware.
`"hw serial" : string`	Serial number of the hardware.
`"srpc domain" : string`	Secure RPC domain.

Note

This function only exists on systems that have the uname(2) or sysinfo(2) system calls.

Only the first five elements are always available.

Method usleep

voidusleep(intusec)

Description

Call the system usleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

Note

The system's usleep function often utilizes the alarm(2) call and might not be perfectly thread safe in combination with simultaneous sleep()'s or alarm()'s. It might also be interrupted by other signals.

If you don't need it to be independant of the system clock, use predef::sleep() instead.

May not be present; only exists if the function exists in the current system.

See also

predef::sleep()sleep()nanosleep()

Method utime

voidutime(stringpath, intatime, intmtime, void|intsymlink)

Description

Set the last access time and last modification time for the path path to atime and mtime repectively. They are specified as unix timestamps with 1 second resolution.

If symlink is set and path refers to a symlink, then the timestamps for the symlink are set. Symlinks are dereferenced otherwise.

Note

Throws errors on failure.

This function is not available on all platforms. On some platforms the symlink flag isn't supported. In that case, the function does nothing if path is a symlink.

See also

System.set_file_atime, System.set_file_mtime

Variable _static_modules

object_static_modules

Description

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

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

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

See also

Builtin, Gmp, _Stdio, _math, _system

Inherit _static_modules: inherit _static_modules : _static_modules

26. Implementation internals

Module Builtin

Class Builtin.FakeObject

Class Builtin.Null

Class Builtin.Pointer

Class Builtin.RandomInterface

Class Builtin.RandomSystem

Class Builtin.Setter

Class Builtin.__Backtrace_Tester__

Class Builtin.__master

Class Builtin.automap_marker

Class Builtin.pike_trampoline

Module __builtin

Module __builtin.Nettle

Class __builtin.Nettle.AE

Class __builtin.Nettle.AE.State

Class __builtin.Nettle.AEAD

Class __builtin.Nettle.AEAD.State

Class __builtin.Nettle.BlockCipher

Module __builtin.Nettle.BlockCipher.CTR

Class __builtin.Nettle.BlockCipher.CTR.State

Class __builtin.Nettle.BlockCipher16Mixin

Class __builtin.Nettle.Cipher

Class __builtin.Nettle.Cipher.State

Class __builtin.Nettle.ECC_Curve

Class __builtin.Nettle.ECC_Curve.Point

Class __builtin.Nettle.Hash

Class __builtin.Nettle.Hash.HKDF

Class __builtin.Nettle.Hash.SCRAM

Module __builtin.Nettle.Hash.HMAC

Class __builtin.Nettle.Hash.HMAC.State

Class __builtin.Nettle.MAC

Class __builtin.Nettle.MAC.State

Class __builtin.Nettle.Sign

Class __builtin.Nettle.__Hash

Class __builtin.Nettle.__Hash.State

Module __builtin.Sql

Class __builtin.Sql.FutureResult

Class __builtin.Sql.Promise

Class __builtin.Sql.ZeroWrapper

Module _static_modules

Module _static_modules.Builtin

Class _static_modules.Builtin.Future (< ValueType >)

Class _static_modules.Builtin.Promise (< ValueType >)

Module _static_modules._math

Module _static_modules._system

Class builtin.Nettle.Hash

Class builtin.Nettle.Hash.State