3.7. Operating System Functions

3.7.1. abort()

Synopsis

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

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

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

Table 3.114. 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.

Usage
errno()
Example
$str = strerror(errno());

Table 3.115. Arguments and Return Values for errno()

Argument Type

Return Type

Description

n/a

Integer

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.

Usage
exec(exec_string)
Example
exec("/bin/ls -l");
Restrictions

Not available with PO_NO_PROCESS_CONTROL or PO_NO_EXTERNAL_PROCESS

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

Usage
exit(return_code)
Example
exit(2);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.117. Arguments and Return Values for exit()

Argument Type

Return Type

Description

Integer

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.

Usage
fork()
Example
$pid = fork();
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.118. Arguments and Return Values for fork()

Argument Type

Return Type

Description

n/a

Integer

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.119. Exceptions Thrown by fork()

err

desc

ILLEGAL-FORK

Cannot fork if more than one thread is running.


3.7.7. getegid()

Synopsis

Returns the effective group ID of the current process.

Usage
getegid()
Example
$egid = getegid();

Table 3.120. Arguments and Return Values for getegid()

Argument Type

Return Type

Description

n/a

Integer

Returns the effective group ID of the current process.


This function does not throw any exceptions.

3.7.8. geteuid()

Synopsis

Returns the effective user ID of the current process.

Usage
geteuid()

Table 3.121. Arguments and Return Values for geteuid()

Argument Type

Return Type

Description

n/a

Integer

Returns the effective user ID of the current process.


This function does not throw any exceptions.

3.7.9. getgid()

Synopsis

Returns the real group ID of the current process.

Usage
getgid()
Example
$gid = getgid();

Table 3.122. Arguments and Return Values for getgid()

Argument Type

Return Type

Description

n/a

Integer

Returns the real group ID of the current process.


This function does not throw any exceptions.

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

Usage
gethostbyaddr(address, [type])
Example
$hostname = gethostbyaddr("192.168.0.33");

Table 3.123. Arguments and Return Values for gethostbyaddr()

Argument Type

Return Type

Description

address, [type]

String

Returns the hostname of the system or NOTHING if the address is unknown.


Table 3.124. Exceptions thrown by gethostbyaddr()

err

desc

GETHOSTBYADDR-ERROR

invalid address or invalid address family passed as arguments


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

Usage
gethostbyaddr_long(address, [type])
Example
$hash = gethostbyaddr_long("192.168.0.33");

Table 3.125. Arguments and Return Values for gethostbyaddr_long()

Argument Type

Return Type

Description

address, [type]

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.126. Host Information Hash

Key

Type

Value

name

String

The official fully-qualified name of the host

aliases

List of Strings

Any hostname aliases for the host

typename

String

The type of network address (either "ipv4" or "ipv6")

type

Integer

One of the Network Address Type Constants (either AF_INET or AF_INET6) corresponding to the type of network addresses given.

len

Integer

The length of the addresses in bytes when represented in binary form.

addresses

List of Strings

All addresses corresponding to the host; the list should have at least 1 element


Table 3.127. Exceptions thrown by gethostbyaddr_long()

err

desc

GETHOSTBYADDR-ERROR

invalid address or invalid address family passed as arguments


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

Usage
gethostbyname(hostname)
Example
$addr = gethostbyname("host1");

Table 3.128. Arguments and Return Values for gethostbyname()

Argument Type

Return Type

Description

hostname

String

Returns the first address corresponding to the hostname passed or NOTHING if the host is unknown.


This function does not throw any exceptions.

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

Usage
gethostbyname_long(hostname)
Example
$hash = gethostbyname_long("host1");

Table 3.129. Arguments and Return Values for gethostbyname_long()

Argument Type

Return Type

Description

hostname

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.14. gethostname()

Synopsis

Returns the hostname of the system.

Usage
gethostname()
Example
$host = gethostname();

Table 3.130. 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.15. getpid()

Synopsis

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

Usage
getpid()
Example
$pid = getpid();

Table 3.131. Arguments and Return Values for getpid()

Argument Type

Return Type

Description

n/a

Integer

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


This function does not throw any exceptions.

3.7.16. getppid()

Synopsis

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

Usage
getppid()
Example
$ppid = getppid();

Table 3.132. Arguments and Return Values for getppid()

Argument Type

Return Type

Description

n/a

Integer

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


This function does not throw any exceptions.

3.7.17. getuid()

Synopsis

Returns the real user ID of the current process.

Usage
getuid()
Example
$uid = getuid();

Table 3.133. Arguments and Return Values for getuid()

Argument Type

Return Type

Description

n/a

Integer

Returns the real user ID of the current process.


This function does not throw any exceptions.

3.7.18. glob()

Synopsis

Returns a list of files matching the string argument.

Usage
glob(string)
Example
$list = glob("*.txt");

Table 3.134. Arguments and Return Values for glob()

Argument Type

Return Type

Description

String

List

Returns a list of files matching the string argument.


This function does not throw any exceptions.

3.7.19. kill()

Synopsis

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

Usage
kill(integer_pid, [integer_signal])
Example
kill($pid, SIGINT);
Restrictions

Not available with PO_NO_EXTERNAL_PROCESS

Table 3.135. Arguments and Return Values for kill()

Argument Type

Return Type

Description

Integer, [Integer]

Integer

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.


This function does not throw any exceptions.

3.7.20. 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()). The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_SETEGID is True. See Library Option Constants for a list of all option constants.

Usage
setegid(egid)
Example
setegid($egid);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.136. Arguments and Return Values for setegid()

Argument Type

Return Type

Description

EGID

Integer

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.137. 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.21. 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()). The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_SETEUID is True. See Library Option Constants for a list of all option constants.

Usage
seteuid(euid)
Example
seteuid($euid);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.138. Arguments and Return Values for seteuid()

Argument Type

Return Type

Description

EUID

Integer

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.139. 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_SETUGID before calling this function.


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

Usage
setgid(gid)
Example
setgid($gid);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.140. Arguments and Return Values for setgid()

Argument Type

Return Type

Description

GID

Integer

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.141. Exceptions thrown by setgid()

err

desc

SETGID-ERROR

missing GID argument to function


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

Usage
setuid(uid)
Example
setuid($uid);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.142. Arguments and Return Values for setuid()

Argument Type

Return Type

Description

UID

Integer

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.143. Exceptions thrown by setuid()

err

desc

SETUID-ERROR

missing UID argument to function


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

Usage
sleep(seconds)
Example
sleep(5s); # sleeps for 5 seconds
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.144. Arguments and Return Values for sleep()

Argument Type

Return Type

Description

Integer or Relative Date/Time

Integer

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.25. stat()

Synopsis

Returns a list of filesystem values for the file passed, following any symbolic links. See also lstat() for a version of this function that does not follow symbolic links, and see hstat() for a version of this function that returns a user-friendly hash instead of a list.

Usage
stat(pathname)
Example
$mode = stat($filepath)[2];
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.145. Arguments and Return Values for stat()

Argument Type

Return Type

Description

String

List

Returns a list of filesystem values for the file passed, following symbolic links. See Stat List below for a description of the list returned by this function.


This function does not throw any exceptions.

Table 3.146. Stat List Description

Position

Data Type

Description

0

Integer

device inode number the file is on

1

Integer

inode of the file

2

Integer

inode protection mode

3

Integer

number of hard links to this file

4

Integer

user ID of the owner

5

Integer

group ID of the owner

6

Integer

device type number

7

Integer

file size in bytes

8

Date/Time

last access time of the file

9

Date/Time

last modified time of the file

10

Date/Time

last change time of the file's inode

11

Integer

block size

12

Integer

blocks allocated for the file


3.7.26. strerror()

Synopsis

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

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

Table 3.147. Arguments and Return Values for strerror()

Argument Type

Return Type

Description

Integer

String

Returns a string corresponding to the error code passed (normally retrieved with errno())


This function does not throw any exceptions.

3.7.27. system()

Synopsis

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

Usage
system(shell_command)
Example
$rc = system("ls -l");
Restrictions

Not available with PO_NO_EXTERNAL_PROCESS

Table 3.148. Arguments and Return Values for system()

Argument

Return Type

Description

String

Integer

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.


This function does not throw any exceptions.

3.7.28. 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 1250ms), however as this function supports a resolution of 1 microsecond, to achieve a resolution below milliseconds, an integer must be used instead of a relative date/time value. See sleep() for a similar function supporting second resolution.

Usage
usleep(file)
Example
usleep(1250ms); # sleeps for 1.25 seconds
usleep(500); # sleeps for 500 microseconds (0.5 milliseconds)
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.149. Arguments and Return Values for usleep()

Argument Type

Return Type

Description

Integer or Relative Date/Time

Integer

Causes the current thread to sleep for a certain number of microseconds (1/1000000 second). Returns 0 for success. Integers are interpreted as microseconds, relative date/time values are interpreted literally.


This function does not throw any exceptions.