Qore Programming Language Reference Manual: Library Functions (original) (raw)

Example:

See also

exit()

◆ basename() [1/2]

nothing Qore::basename	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ basename() [2/2]

Returns a string giving the last element of a file path (meant to be the filename)

Code Flags:

Qore::Option::HAVE_CLOSE_ALL_FD

Parameters

Returns

a string giving the last element of the given file path (meant to be the filename)

Example:

string fn = basename("/usr/local/bin/file_name");

See also

dirname()

◆ close_all_fd()

nothing Qore::close_all_fd	(	*softbool	strd	)

closes all possible file descriptors; useful in "daemon" processes that may have inherited open file descriptors

Platform Availability:

Restrictions:

Parameters

strd	if True then also stdin, stdout, and stderr are closed, otherwise fds > 2 are closed

Example:

Note

if there are file descriptors open by Qore when this function is called, this function will also close those file descriptors; normally this function should only be used when starting a new process after a fork() and exec() to close any inherited descriptors, for example

◆ dirname() [1/2]

nothing Qore::dirname	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ dirname() [2/2]

Returns a string giving the path up to a file but not the filename itself.

Code Flags:

Qore::PO_NO_EXTERNAL_PROCESS, Qore::PO_NO_PROCESS_CONTROL

Parameters

Returns

a string giving the path up to a file but not the filename itself; if no directory separator characters can be found in the path, "." is returned (meaning the current directory)

Example:

string dir = dirname("/usr/local/bin/file_name");

See also

basename()

◆ errno()

Returns the error code of the last error that occurred in the current thread.

Returns

the error code of the last error that occurred in the current thread (see Error Constants for possible error code values)

Example:

if (unlink(path))

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

See also

strerror() for a function that gives the string description for the error number returned by this function

◆ exec()

nothing Qore::exec	(	string	command	)

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

Restrictions:

Parameters

command	the executable to execute and any command-line arguments; the command is executed internally by a call to execvp() (3)

Example:

exec("/usr/bin/xterm -bg black -fg white -sb -sl 2000");

◆ exit()

nothing Qore::exit	(	softint	rc = 0	)

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

Restrictions:

Parameters

rc	the return code for the process (0 = no error; success)

Example:

See also

abort()

◆ fork()

Creates a copy of the current process with a new PID; returns 0 in the child process; returns the child's PID in the parent process.

This function will throw an ILLEGAL-FORK exception if more than one thread is running

Platform Availability:

Qore::Option::HAVE_FORK

Restrictions:

Qore::Option::HAVE_GET_NETIF_LIST

Returns

0 in the child process; returns the child's PID in the parent process; if an error occurs, then -1 is returned, in this case no child process was started and the error number can be retrieved with the errno() function

Example:

int pid;

if (pid = fork())

printf("child has PID %d\n", pid);

Exceptions

ILLEGAL-FORK	Cannot fork if more than one thread is running

Note

after a fork(), the only safe call is exec(), many system calls are not async-signal safe, including pthread_create() which is used to start new threads.
the Qore process will crash if unsafe operations are called after a fork()
the signal-handling thread cannot be reliably started on many platforms (ex: FreeBSD) after a fork(), therefore signal handling is disabled in the child process after a fork()
on Darwin (OS/X) threading primitives are unusable in the child process after a fork()

◆ get_netif_list()

returns a list of network interfaces

Platform Availability:

Restrictions:

Example:

list<hash> l = get_netif_list();

results for example into:

list: (8 elements)

[0]=hash: (5 members)

interface : "lo"

address : "00:00:00:00:00:00"

address_desc : "mac<00:00:00:00:00:00>"

family : 17

familystr : "mac"

[1]=hash: (5 members)

interface : "eth0"

address : "44:8a:5b:ba:13:50"

address_desc : "mac<44:8a:5b:ba:13:50>"

family : 17

familystr : "mac"

[2]=hash: (5 members)

interface : "lo"

address : "127.0.0.1"

address_desc : "ipv4(127.0.0.1)"

family : 2

familystr : "ipv4"

[3]=hash: (5 members)

interface : "eth0"

address : "192.168.20.4"

address_desc : "ipv4(192.168.20.4)"

family : 2

familystr : "ipv4"

[4]=hash: (5 members)

interface : "lo"

address : "::1"

address_desc : "ipv6[::1]"

family : 10

familystr : "ipv6"

[5]=hash: (5 members)

interface : "eth0"

address : "fe80::213:3bff:fe0f:d5e1"

address_desc : "ipv6[fe80::213:3bff:fe0f:d5e1]"

family : 10

familystr : "ipv6"

Returns

returns a list of network interfaces available on the local machine

◆ getaddrinfo()

list< hash< auto > > Qore::getaddrinfo	(	*string	node,
*softstring	service,
softint	family = AF_UNSPEC,
softint	flags = 0
)

Returns a list of Address Information Hash for the given node name or string address; if no lookup can be performed then an exception is thrown.

Either node or service may be NOTHING but not both or a QOREADDRINFO-GETINFO-ERROR exception will be thrown

Restrictions:

Code Flags:

RET_VALUE_ONLY

Parameters

Returns

a list of Address Information Hash for the given node name or string address; if no lookup can be performed then an exception is thrown

Example:

list<hash> l = getaddrinfo("localhost");

Exceptions

QOREADDRINFO-GETINFO-ERROR	nodename nor servname provided, or not known

◆ getegid()

◆ geteuid()

◆ getgid()

◆ getgroups()

◆ gethostbyaddr() [1/2]

nothing Qore::gethostbyaddr	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ gethostbyaddr() [2/2]

Returns the official hostname corresponding to the network address passed as an argument.

If the address family is invalid or the address string is not a valid address for the given family a GETHOSTBYADDR-ERROR exception will be thrown.

Restrictions:

Code Flags:

Parameters

Returns

the official hostname corresponding to the network addressed passed as an argument

Example:

*string hostname = gethostbyaddr("192.168.0.33");

if (!exists hostname)

printf("address lookup on 192.168.0.33 failed\n", host);

Exceptions

GETHOSTBYADDR-ERROR	invalid address for the given family or invalid address family

See also

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

◆ gethostbyaddr_long() [1/2]

nothing Qore::gethostbyaddr_long	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ gethostbyaddr_long() [2/2]

Returns a hash representing all host and address information corresponding to the address and address type passed as arguments.

If the address family is invalid or the address string is not a valid address for the given family a GETHOSTBYADDR-ERROR exception will be thrown.

Restrictions:

Code Flags:

Parameters

Returns

a hash representing all host and address information corresponding to the address and address type passed as arguments

Example:

*hash ah = gethostbyaddr_long("192.168.0.33");

if (!ah)

printf("address lookup on 192.168.0.33 failed\n", host);

Exceptions

GETHOSTBYADDR-ERROR	invalid address for the given family or invalid address family

See also

gethostbyaddr() for a simpler version of this function that returns just a single hostname for the address

◆ gethostbyname() [1/2]

nothing Qore::gethostbyname	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ gethostbyname() [2/2]

Returns the first address corresponding to the hostname passed as an argument or NOTHING if the lookup fails.

Restrictions:

Code Flags:

Parameters

Returns

the first address corresponding to the hostname passed as an argument or NOTHING if the lookup fails

Example:

*string addr = gethostbyname(host);

if (!exists host)

printf("address lookup on %y failed; hostname unknown\n", host);

See also

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

◆ gethostbyname_long() [1/2]

nothing Qore::gethostbyname_long	(	)

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Code Flags:

◆ gethostbyname_long() [2/2]

*hash< auto > Qore::gethostbyname_long	(	string	name	)

Returns a hash representing all host and address information corresponding to the hostname passed as an argument.

Restrictions:

Code Flags:

Parameters

Returns

a hash representing all host and address information corresponding to the hostname passed as an argument

Example:

*hash ah = gethostbyname_long(host);

if (!ah)

printf("address lookup on %y failed; hostname unknown\n", host);

See also

gethostbyname() for a version of this function that returns just the first network address corresponding to the hostname

◆ gethostname()

Returns the hostname of the system.

Returns

the hostname of the system

Restrictions:

Code Flags:

Qore::PO_NO_EXTERNAL_PROCESS

Example:

string host = gethostname();

◆ getpid()

◆ getppid()

◆ getuid()

◆ kill() [1/2]

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:

Code Flags:

Qore::PO_NO_EXTERNAL_PROCESS

◆ kill() [2/2]

int Qore::kill	(	softint	pid,
softint	sig = SIGHUP
)

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

Platform Availability:

Qore::Option::HAVE_KILL

Restrictions:

Parameters

pid	the pid argument can have the following interpretations: > 0: the signal is sent to the process ID given 0: the signal is sent to all processes whose group ID is equal to the process group ID of the sender, and for which the process has permission -1: if the user has super-user privileges, the signal is sent to all processes excluding system processes and the process sending the signal. If the user is not the super user, the signal is sent to all processes with the same uid as the user, excluding the process sending the signal. No error is returned if any process could be signaled.
sig	the signal number to send to the process or processes

Returns

0 means success (no error), or -1 meaning an error occurred; in this case check errno() for the error

Example:

if (kill(pid, SIGTERM))

printf("error sending signal to pid %d: %s\n", pid, strerror());

◆ qore_get_library_options()

int Qore::qore_get_library_options	(	)

◆ qore_set_library_options()

int Qore::qore_set_library_options	(	int	opts	)

◆ rand()

Returns a random non-negative 64-bit integer number.

This function uses the C library function random() to generate the number if available on the current platform, otherwise uses rand().

Returns

a random non-negative 64-bit integer number

Code Flags:

Qore::Option::HAVE_UNIX_USERMGT

Example:

See also

srand() for a function to seed the random number generator

Since

Qore 0.8.13 the random number generator is seeded randomly when the Qore library is initialized

◆ setegid()

int Qore::setegid	(	softint	gid	)

Changes the process effective group ID according to the argument passed.

Platform Availability:

Restrictions:

Qore::Option::HAVE_SETEUID

Parameters

Returns

0 if no error occurred; -1 if an error occurred, in which case errno() and/or strerror() can be used to retrieve the error

Example:

if (setegid(gid))

printf("setegid %d: %s\n", gid, strerror());

◆ seteuid()

int Qore::seteuid	(	softint	uid	)

Changes the effective process user ID according to the argument passed.

Platform Availability:

Restrictions:

Parameters

Returns

0 if no error occurred; -1 if an error occurred, in which case errno() and/or strerror() can be used to retrieve the error

Example:

if (seteuid(uid))

printf("seteuid %d: %s\n", uid, strerror());

◆ setgid()

int Qore::setgid	(	softint	gid	)

◆ setgroups()

nothing Qore::setgroups	(	softlist< softint >	gids	)

◆ setsid()

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.

Returns

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; if an error occurs, setsid() returns -1 and errno() and/or strerror() can be used to check the error.

Restrictions:

Example:

if (setsid() == -1)

printf("setsid(): %s\n", strerror());

◆ setuid()

int Qore::setuid	(	softint	uid	)

◆ sleep() [1/2]

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:

Code Flags:

◆ sleep() [2/2]

int Qore::sleep	(	softint	seconds	)

Causes the current thread to sleep for a certain number of seconds.

Restrictions:

Parameters

seconds	The amount of time in seconds to sleep; integer arguments are interpreted literally as a number of seconds to sleep, however a relative date/time value can be given instead of an integer to make the source more readable (ex: 5s), however as this function only supports a resolution of 1 second, milliseconds and microseconds are ignored if passed in a relative date/time value

Returns

should always return 0 for success

Example:

See also

usleep() for a similar function supporting microsecond resolution

◆ srand() [1/2]

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:

Code Flags:

◆ srand() [2/2]

nothing Qore::srand	(	softint	seed	)

Seeds the random number generator with the integer passed.

This function uses the C library function srandom() if available on the current platform, otherwise uses srand()

Restrictions:

Parameters

seed	the seed for the random number generator (only the least-significant 32-bits are used)

Example:

See also

rand() for a function that returns a random number related to the seed given here

Since

Qore 0.8.13 the random number generator is seeded randomly when the Qore library is initialized

◆ strerror() [1/2]

Returns the string corresponding to the last error that occurred in the current thread.

Returns

the string corresponding to the last error that occurred in the current thread

Code Flags:

Example:

if (unlink(path))

printf("%s: %s\n", path, strerror());

Since

Qore 0.8.4 this variant of the function automatically uses the last error value for the current thread

◆ strerror() [2/2]

string Qore::strerror	(	softint	err	)

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

Code Flags:

Qore::PO_NO_EXTERNAL_PROCESS

Parameters

err	the error code to retrieve the description for (generally provided by errno())

Returns

the string corresponding to the error code passed; if the error code is unknown, then a string like "Unknown error: -1" is returned

Example:

if (unlink(path))

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

◆ system() [1/2]

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:

Code Flags:

◆ system() [2/2]

◆ usleep() [1/3]

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:

Code Flags:

◆ usleep() [2/3]

Causes the current thread to sleep for a certain number of microseconds.

Restrictions:

Parameters

d	A time value giving the amount of time in microseconds to sleep; this should be a relative date/time value to make the source more readable (ex: 250ms)

Returns

should always return 0 for success

Example:

See also

sleep() for a similar function supporting second resolution

Note

both sleep() and usleep() are implemented internally by calls to nanosleep() (2) if available on the current platform, otherwise both are implemented by calls to usleep() (3)

◆ usleep() [3/3]

int Qore::usleep	(	softint	usecs	)

Causes the current thread to sleep for a certain number of microseconds.

Restrictions: