3.7. Operating System Functions

3.7. Operating System Functions
Prev	Chapter 3. Function Library	Next

3.7.1. abort()

Synopsis

Aborts the current program (this function does not return).

Prototype

nothing abort()

Example

abort();

Restrictions

Not available with PO_NO_PROCESS_CONTROL

This function does not throw any exceptions.

3.7.2. basename()

Synopsis

Returns a string giving the last element of a file path.

Prototype

string basename(string)

nothing basename() (RT_NOOP)

Example

$str = basename("/usr/local/bin/file_name"); # returns "file_name"

Table 3.132. Arguments and Return Values for basename()

Argument Type	Return Type	Description
`string`	`string`	Returns the last element in a file path (meant to be the filename).

This function does not throw any exceptions.

3.7.3. errno()

Synopsis

Returns the error code of the last error that occurred in the current thread. See strerror() for a function that gives the string description for the error number returned by this function.

Prototype

int errno()

Example

$str = strerror(errno());

Table 3.133. Arguments and Return Values for errno()

Argument Type	Return Type	Description
n/a	`int`	The error code of the most recent error in the current thread is returned.

This function does not throw any exceptions.

3.7.4. exec()

Synopsis

Replaces the current process image with another. This function does not return.

Prototype

nothing exec(string)

nothing exec() (RT_NOOP)

Example

exec("/bin/ls -l");

Restrictions

Not available with PO_NO_PROCESS_CONTROL or PO_NO_EXTERNAL_PROCESS

Table 3.134. Arguments and Return Values for exec()

Argument Type	Return Type	Description
`string`	n/a	The process and any arguments to the process to execute. This function does not return.

This function does not throw any exceptions.

3.7.5. exit()

Synopsis

Exits the program with the return code passed (this function does not return).

Prototype

nothing exit(any = 0)

Example

exit(2);

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.135. Arguments and Return Values for exit()

Argument Type	Return Type	Description
`any`	n/a	Exits the program with the return code set to the value of the argument passed converted to an integer if necessary.

This function does not throw any exceptions.

3.7.6. fork()

Synopsis

Creates a copy of the current process with a new PID. Returns 0 in the child process, the child's PID in the parent process. This function will throw an exception if more than one thread is running.

Prototype

int fork()

Example

$pid = fork();

Platform Availability

HAVE_FORK

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.136. Arguments and Return Values for fork()

Argument Type	Return Type	Description
n/a	`int`	The child's PID is returned in the parent process, 0 is returned in the child's process. If -1 is returned, then no child was started and the error number can be retrieved with the errno() function.

Table 3.137. Exceptions Thrown by fork()

err	desc
`ILLEGAL-FORK`	Cannot fork if more than one thread is running.
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_FORK` before calling this function.

3.7.7. getaddrinfo()

Synopsis

Returns a list of address information hashes for the given node name or string address. If no lookup can be performed then an exception is thrown.

Prototype

list getaddrinfo(*string $node, *softstring $service, softint $family = AF_UNSPEC, softint $flags = 0) (CONST)

Example

my list $l = getaddrinfo("localhost");

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.138. Arguments for getaddrinfo()

Argument	Description
`*string $node`	The host name or node name to look up. Either `$node` or `$service` may be NOTHING but not both or an exception will be thrown.
`*softstring $service`	The service name to look up to a port number. Either `$node` or `$service` may be NOTHING but not both or an exception will be thrown.
`softint $family = AF_UNSPEC`	The address family for the lookup, must be one of `AF_INET`, `AF_INET6`, or `AF_UNSPEC`, meaning to return all possible addresses.
`softint $flags = 0`	See Address Information Constants.

Table 3.139. Return Value for getaddrinfo()

Return Type	Description
`list`	Returns a list of address information hashes for the given node name or string address. If no lookup can be performed then an exception is thrown.

Table 3.140. Exceptions Thrown by getaddrinfo()

err	desc
`QOREADDRINFO-GETINFO-ERROR`	nodename nor servname provided, or not known.

Table 3.141. Address Information Hash

Key	Type	Description
`address`	`string`	A valid address of the host, for example: `"::1"`.
`address_desc`	`string`	A descriptive string of the address containing the address family, for example: `"ipv6[::1]"`.
`family`	`int`	The network address family; see Network Address Family Constants.
`familystr`	`string`	A descriptive string for the network address family, for example: `"ipv6"`.
`addrlen`	`int`	The length of the internal network address data structure (not normally needed in Qore but provided anyway).

3.7.8. getegid()

Synopsis

Returns the effective group ID of the current process.

Prototype

int getegid() (CONST)

Example

$egid = getegid();

Platform Availability

HAVE_UNIX_USERMGT

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.142. Arguments and Return Values for getegid()

Argument Type	Return Type	Description
n/a	`int`	Returns the effective group ID of the current process.

Table 3.143. Exceptions Thrown by getegid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.9. geteuid()

Synopsis: Returns the effective user ID of the current process.
Prototype: int geteuid() (CONST)
Platform Availability: HAVE_UNIX_USERMGT
Restrictions: Not available with PO_NO_EXTERNAL_INFO

Table 3.144. Arguments and Return Values for geteuid()

Argument Type	Return Type	Description
n/a	`int`	Returns the effective user ID of the current process.

Table 3.145. Exceptions Thrown by geteuid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.10. getgid()

Synopsis

Returns the real group ID of the current process.

Prototype

int getgid(CONST)

Example

my int $gid = getgid();

Platform Availability

HAVE_UNIX_USERMGT

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.146. Arguments and Return Values for getgid()

Argument Type	Return Type	Description
n/a	`int`	Returns the real group ID of the current process.

Table 3.147. Exceptions Thrown by geteuid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.11. gethostbyaddr()

Synopsis

Returns the official hostname corresponding to the network addressed passed as an argument. If the second argument giving the address type is not passed, then AF_INET (IPv4) is assumed. See Network Address Type Constants for valid values for the second argument. If the address family is invalid or the address string is not a valid address for the given family an exception will be thrown.

For a version of this function that returns all host information, including all hostname aliases and all addresses, see gethostbyaddr_long().

Prototype

*string gethostbyaddr(string $addr, softint $type = AF_INET) (CONST)

nothing gethostbyaddr() (RT_NOOP)

Example

my *string $hostname = gethostbyaddr("192.168.0.33");

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.148. Arguments and Return Values for gethostbyaddr()

Argument Type	Return Type	Description
`string $addr, softint $type = AF_INET`	`*string`	Returns the hostname of the system as a string or NOTHING if the address is unknown.

Table 3.149. Exceptions thrown by gethostbyaddr()

err	desc
`GETHOSTBYADDR-ERROR`	invalid address or invalid address family passed as arguments

3.7.12. gethostbyaddr_long()

Synopsis

Returns a hash representing all host and address information corresponding to the network addressed passed as an argument. See Host Information Hash for a description of the return value.

If the second argument giving the address type is not passed, then AF_INET (IPv4) is assumed. See Network Address Type Constants for valid values for the second argument. If the address family is invalid or the address string is not a valid address for the given family an exception will be thrown.

For a version of this function that returns just the official hostname corresponding to the address, see gethostbyaddr().

Prototype

*hash gethostbyaddr_long(string $addr, softint $type = AF_INET) (CONST)

nothing gethostbyaddr_long() (RT_NOOP)

Example

my *hash $hash = gethostbyaddr_long("192.168.0.33");

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.150. Arguments and Return Values for gethostbyaddr_long()

Argument Type	Return Type	Description
`string $addr, softint $type = AF_INET`	`*hash`	Returns a hash representing all host and address information corresponding to the network address passed or NOTHING if the address is unknown.

Table 3.151. Host Information Hash

Key	Type	Value
`name`	`string`	The official fully-qualified name of the host
`aliases`	list of string	Any hostname aliases for the host
`typename`	`string`	The type of network address (either "ipv4" or "ipv6")
`type`	`int`	One of the Network Address Type Constants (either `AF_INET` or `AF_INET6`) corresponding to the type of network addresses given.
`len`	`int`	The length of the addresses in bytes when represented in binary form.
`addresses`	list of string	All addresses corresponding to the host; the list should have at least 1 element

Table 3.152. Exceptions thrown by gethostbyaddr_long()

err	desc
`GETHOSTBYADDR-ERROR`	invalid address or invalid address family passed as arguments

3.7.13. gethostbyname()

Synopsis

Returns the first address corresponding to the hostname passed as an argument.

For a version of this function that returns all host information, including all hostname aliases and all addresses, see gethostbyname_long().

Prototype

*string gethostbyname(string $name) (CONST)

nothing gethostbyname() (RT_NOOP)

Example

my *string $addr = gethostbyname("host1");

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.153. Arguments and Return Values for gethostbyname()

Argument Type	Return Type	Description
`string $name`	`*string`	Returns the first address corresponding to the hostname passed as a string or NOTHING if the host is unknown.

This function does not throw any exceptions.

3.7.14. gethostbyname_long()

Synopsis

Returns a hash representing all host and address information corresponding to the hostname passed as an argument. See Host Information Hash for a description of the return value.

For a version of this function that returns just the first network address corresponding to the hostname, see gethostbyname().

Prototype

*hash gethostbyname_long(string $name) (CONST)

Example

my *hash $hash = gethostbyname_long("host1");

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.154. Arguments and Return Values for gethostbyname_long()

Argument Type	Return Type	Description
`string $name`	`*hash`	Returns a hash representing all host and address information corresponding to the hostname passed or NOTHING if the host is unknown.

This function does not throw any exceptions.

3.7.15. gethostname()

Synopsis

Returns the hostname of the system.

Prototype

string gethostname()

Example

$host = gethostname();

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.155. Arguments and Return Values for gethostname()

Argument Type	Return Type	Description
n/a	`string`	Returns the hostname of the system.

This function does not throw any exceptions.

3.7.16. getpid()

Synopsis

Returns the PID (process ID) of the current process.

Prototype

int getpid() (CONST)

Example

$pid = getpid();

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.156. Arguments and Return Values for getpid()

Argument Type	Return Type	Description
n/a	`int`	Returns the PID (process ID) of the current process.

This function does not throw any exceptions.

3.7.17. getppid()

Synopsis

Returns the PID (process ID) of the parent process of the current process.

Prototype

int getppid() (CONST)

Example

$ppid = getppid();

Platform Availability

HAVE_GETPPID

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.157. Arguments and Return Values for getppid()

Argument Type	Return Type	Description
n/a	`int`	Returns the PID (process ID) of the parent of the current process.

Table 3.158. Exceptions Thrown by getppid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_GETPPID` before calling this function.

3.7.18. getuid()

Synopsis

Returns the real user ID of the current process.

Prototype

int getuid() (CONST)

Example

$uid = getuid();

Platform Availability

HAVE_UNIX_USERMGT

Restrictions

Not available with PO_NO_EXTERNAL_INFO

Table 3.159. Arguments and Return Values for getuid()

Argument Type	Return Type	Description
n/a	`int`	Returns the real user ID of the current process.

Table 3.160. Exceptions Thrown by getuid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.19. glob()

Synopsis

Returns a list of files matching the string argument or NOTHING if the call to glob() fails.

Prototype

*list glob(string)

nothing glob() (RT_NOOP)

Example

my *list $list = glob("*.txt");

Table 3.161. Arguments and Return Values for glob()

Argument Type	Return Type	Description
`string`	`*list`	Returns a list of files matching the string argument or NOTHING if the call to `glob()` fails.

This function does not throw any exceptions.

3.7.20. kill()

Synopsis

Sends a signal to a process, if no signal number is given, then SIGHUP is sent by default.

Prototype

int kill(softint $pid, softint $signal = SIGHUP)

nothing kill() (RT_NOOP)

Example

kill($pid, SIGINT);

Platform Availability

HAVE_KILL

Restrictions

Not available with PO_NO_EXTERNAL_PROCESS

Table 3.162. Arguments and Return Values for kill()

Argument Type	Return Type	Description
`int $pid, int $signal = SIGHUP`	`int`	Sends a signal to a process, if the optional signal number is not given, then SIGHUP is sent. A 0 return value means that the signal was succesfully sent.

Table 3.163. Exceptions Thrown by kill()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_KILL` before calling this function.

3.7.21. setegid()

Synopsis

Changes the process effective group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()).

Prototype

int setegid(softint)

Example

setegid($egid);

Platform Availability

HAVE_SETEGID

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.164. Arguments and Return Values for setegid()

Argument Type	Return Type	Description
`softint`	`int`	Changes the process effective group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Table 3.165. Exceptions thrown by setegid()

err	desc
`SETEGID-ERROR`	missing EGID argument to function
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available; for maximum portability, check the constant `HAVE_SETEGID` before calling this function.

3.7.22. seteuid()

Synopsis

Changes the process effective user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()).

Prototype

int seteuid(softint)

Example

seteuid($euid);

Platform Availability

HAVE_SETEUID

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.166. Arguments and Return Values for seteuid()

Argument Type	Return Type	Description
`softint`	`int`	Changes the process effective user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Table 3.167. Exceptions thrown by seteuid()

err	desc
`SETEUID-ERROR`	missing EUID argument to function
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available; for maximum portability, check the constant `HAVE_SETEUID` before calling this function.

3.7.23. setgid()

Synopsis

Changes the process group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Prototype

int setgid(softint)

Example

setgid($gid);

Platform Availability

HAVE_UNIX_USERMGT

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.168. Arguments and Return Values for setgid()

Argument Type	Return Type	Description
`softint`	`int`	Changes the process group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Table 3.169. Exceptions Thrown by setgid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.24. setsid()

Synopsis

Creates a new session lead by the calling process.

The calling process is the session leader of the new session, is the process group leader of a new process group and has no controlling terminal. The calling process is the only process in either the session or the process group.

Upon successful completion, the setsid() function returns the value of the process group ID of the new process group, which is the same as the process ID of the calling process.

Prototype

int setsid()

Example

my int $rc = setsid();

Platform Availability

HAVE_SETSID

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.170. Arguments and Return Values for setsid()

Argument Type	Return Type	Description
n/a	`int`	Returns the current pid on success or -1 for errors (in which case the error code can be retrieved with errno())

Table 3.171. Exceptions Thrown by setsid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_SETSID` before calling this function.

3.7.25. setuid()

Synopsis

Changes the process user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Prototype

int setuid(softint)

Example

setuid($uid);

Platform Availability

HAVE_UNIX_USERMGT

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.172. Arguments and Return Values for setuid()

Argument Type	Return Type	Description
`softint`	`int`	Changes the process user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())

Table 3.173. Exceptions Thrown by setuid()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_USERMGT` before calling this function.

3.7.26. sleep()

Synopsis

Causes the current thread to sleep for a certain number of seconds. Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable (ie 5s), however as this function only supports a resolution of 1 second, milliseconds are ignored if passed to this function. See usleep() for a similar function supporting microsecond resolution.

Prototype

int sleep(softint)

int sleep(date)

nothing sleep() (RT_NOOP)

Example

sleep(5s); # sleeps for 5 seconds

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.174. Arguments and Return Values for sleep()

Argument Type	Return Type	Description
`softint or date`	`int`	Causes the current thread to sleep for a number of seconds equal to the argument passed. Returns 0 for success. An integer argument is interpreted as a number of seconds to sleep, relative date/time values are interpreted literally.

This function does not throw any exceptions.

3.7.27. strerror()

Synopsis

Returns the string corresponding to the error code passed (generally retrieved with errno()).

Prototype

string strerror(softint $errno) (CONST)

nothing strerror() (RT_NOOP)

Example

printf("%s\n", strerror(errno()));

Table 3.175. Arguments and Return Values for strerror()

Argument Type	Return Type	Description
`softint $errno`	`string`	Returns a string corresponding to the error code passed (normally retrieved with errno())

This function does not throw any exceptions.

3.7.28. system()

Synopsis

Executes an external program and returns the exit code of the process.

Prototype

int system(string)

nothing system() (RT_NOOP)

Example

$rc = system("ls -l");

Platform Availability

HAVE_SYSTEM

Restrictions

Not available with PO_NO_EXTERNAL_PROCESS

Table 3.176. Arguments and Return Values for system()

Argument	Return Type	Description
`string`	`int`	If shell meta-characters are present in the string to be executed, Qore uses the C library system() call to execute the external program, otherwise a fork() and exec() is used. The exit code of the process is returned as an integer.

Table 3.177. Exceptions Thrown by system()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_SYSTEM` before calling this function.

3.7.29. usleep()

Synopsis

Causes the current thread to sleep for a certain number of microseconds (1/1000000 second). Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable (ie 1250us). See sleep() for a similar function supporting second resolution.

Prototype

int usleep(date $time)

int usleep(softint $microseconds)

nothing usleep() (RT_NOOP)

Example

usleep(1250us); # sleeps for 1250 microseconds (1.25 milliseconds)

usleep(500);    # sleeps for 500 microseconds (0.5 milliseconds)

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.178. Arguments and Return Values for usleep()

Argument Type	Return Type	Description
`softint $microseconds`	`int`	Causes the current thread to sleep for the given number of microseconds (1/1000000 second). Returns 0 for success.
`date $time`	`int`	Causes the current thread to sleep for the given period of time with a resolution of microseconds (1/1000000 second). Returns 0 for success.

This function does not throw any exceptions.

Prev	Up	Next
3.6. String Functions	Home	3.8. Cryptographic Functions