OS abstraction layer. More...

Classes
class	QiException
	Custom exception that may be thrown by QI methods. More...
struct	timeval
	qi::os::timeval struct similar to POSIX timeval More...
Functions
FILE *	fopen (const char filename, const char mode)
	Open a file and returns and handle on it.
int	stat (const char filename, struct stat pstat)
	Get file status.
int	checkdbg ()
std::string	home ()
	Return path to the current user's HOME.
std::string	mktmpdir (const char *prefix="")
	Return a writable temporary directory.
std::string	tmp ()
	Return the system's temporary directory.
std::string	gethostname ()
	Get the system's hostname.
int	isatty (int fd=1)
	Test if descriptor represents a terminal.
bool	fnmatch (const std::string &pattern, const std::string &string)
char *	strdup (const char *src)
int	snprintf (char str, size_t size, const char format,...)
	Implement POSIX compliant snprintf.
std::string	getenv (const char *var)
	Get an environment variable.
int	setenv (const char var, const char value)
	Change or add an environment variable.
std::string	timezone ()
	Return the timezone.
void	sleep (unsigned int seconds)
	Sleep for the specified number of seconds.
void	msleep (unsigned int milliseconds)
	Sleep for the specified number of milliseconds.
int	gettimeofday (qi::os::timeval *tp)
	The gettimeofday() function shall obtain the current time.
qi::int64_t	ustime ()
	Return elapsed time since program started in microseconds.
std::pair< int64_t, int64_t >	cputime ()
	Return CPU time used by the calling thread as a pair (userTime, systemTime) in microseconds.
qi::os::timeval	operator+ (const qi::os::timeval &lhs, const qi::os::timeval &rhs)
qi::os::timeval	operator+ (const qi::os::timeval &lhs, long us)
qi::os::timeval	operator- (const qi::os::timeval &lhs, const qi::os::timeval &rhs)
qi::os::timeval	operator- (const qi::os::timeval &lhs, long us)
void *	dlopen (const char *filename, int flag=-1)
	Load a dynamic library.
int	dlclose (void *handle)
	Decrements the reference count on the dynamic library.
void *	dlsym (void handle, const char symbol)
	Get the address where the symbol is loaded into memory.
const char *	dlerror (void)
	Returns a human readable string of the error code.
int	spawnvp (char *const argv[])
	Create and execute a new process.
int	spawnlp (const char *argv,...)
	Create and execute a new process.
int	system (const char *command)
	Execute a shell command.
int	getpid ()
	Get the process identifier.
int	gettid ()
	Get the thread identifier.
int	waitpid (int pid, int *status)
	Wait for process to change state.
int	kill (int pid, int sig)
	Send a signal to a process.
unsigned short	findAvailablePort (unsigned short port)
	Find the first available port starting at port number in parameter.
std::map< std::string, std::vector< std::string > >	hostIPAddrs (bool ipv6Addr=false)
	Find all network adapters and corresponding IPs.
void	setCurrentThreadName (const std::string &name)
	Set the current thread name to the string in parameter.
std::string	currentThreadName ()
	returns the current thread name as a std::string
bool	setCurrentThreadCPUAffinity (const std::vector< int > &cpus)
long	numberOfCPUs ()
std::string	getMachineId ()
	Returns an unique uuid for the machine.
std::string	generateUuid ()
	Generate a universally unique identifier.
size_t	memoryUsage (unsigned int pid)
	Get the memory usage of a process.
QI_API_DEPRECATED std::string	tmpdir (const char *prefix="")
	Return a temporary directory.

Detailed Description

OS abstraction layer.

 * This module provides some functions following POSIX convention to manipulate
 * the operating system layer in a cross-platform way.
 *
 * .. note::
 *
 *     Every path taken in parameter *must* be encoded in UTF-8. Every path
 *     returned is encoded in UTF-8.
 *

Function Documentation

int qi::os::checkdbg ( )

qi::os::cputime ( )

Return CPU time used by the calling thread as a pair (userTime, systemTime) in microseconds.

Warning:: under Linux, systemTime is always 0 and merged in userTime. Also value might be inaccurate if CPU frequency scaling is used and the thread is not constrained to a single core.

qi::os::currentThreadName ( )

returns the current thread name as a std::string

Returns:: a std::string of at most 16 characters

Warning:: Not implemented on Windows, always returns an empty string

/**

qi::os::dlclose ( void * handle )

Decrements the reference count on the dynamic library.

Parameters:

handle The dynamic library handle.

Returns:: This function returns 0 on success, and non-zero on error.

 * Decrements the reference count on the dynamic library handle. If the
 * reference count drops to zero and no other loaded library uses symbols in
 * it, then the dynamic library is unloaded.
 *
 * If there is an error you can look which one with dlerror function provided in
 * this same module.
 *
 * .. seealso:: :cpp:func:`qi::os::dlerror(void)` for more details on the error.
 *
 * .. versionadded:: 1.12
 *

qi::os::dlerror ( void )

Returns a human readable string of the error code.

Returns:: NULL if no error has occurred since it was last called. An human readable string otherwise.

.. warning:: On windows, return value may be modified by another function unrelated to qi::os::dlopen familly. This function does not ensure that error value is 0 at initialisation. You may reset error value before a call to any qi::os::dl{open, sym, close} functions with a first call to this function.

 * Returns a human readable string describing the most recent error that
 * occurred from :cpp:func:`qi::os::dlopen(const char*, int)`,
 * :cpp:func:`qi::os::dlsym(void*, const char*)` or
 * :cpp:func:`qi::os::dlclose(void*)` since the last call to
 * :cpp:func:`qi::os::dlerror()`.
 *
 * .. versionadded:: 1.12
 *

qi::os::dlopen	(	const char *	filename,
		int	flag = `-1`
	)

Load a dynamic library.

Parameters:

filename	Name of the dynamic library.
flag	Flags used to load the dynamic library.

Returns:: A handle to the library, or 0 on error.

 * Loads the dynamic library file named by the null-terminated string filename
 * and returns an opaque "handle" for the dynamic library. If filename is NULL,
 * then the returned handle is for the main program.
 *
 * No flag is supported on windows platform. Otherwise, see ``man 0p dlfcn.h``
 * for more information on flags available. If not given, ``RTLD_NOW`` is used.
 *
 * .. seealso:: :cpp:func:`qi::os::dlerror(void)` for more details on the error.
 *
 * .. versionadded:: 1.12
 *

qi::os::dlsym	(	void *	handle,
		const char *	symbol
	)

Get the address where the symbol is loaded into memory.

Parameters:

handle	Handle on a dynamic library returned by dlopen().
symbol	The null-terminated symbol name.

Returns:: The address of the symbol, or 0 on error.

 * If the symbol is not found in the specified library or any of the libraries
 * that were automatically loaded by :cpp:func:`qi::os::dlopen()` when that
 * library was loaded, :cpp:func:`qi::os::dlsym()` returns 0.
 *
 * .. seealso:: :cpp:func:`qi::os::dlerror(void)` for more details on the error.
 *
 * .. versionadded:: 1.12
 *

qi::os::findAvailablePort ( unsigned short port )

Find the first available port starting at port number in parameter.

Parameters:

port	First port tested, then each port following it is tested one by one until one available is found.

Returns:: Available port or 0 on error

 * .. warning::
 *
 *     This function is not thread safe and suffers from a race condition. You
 *     should avoid calling it and call listen on port 0 instead. This will pick
 *     a random port with no race condition.
 *
 * .. versionadded:: 1.14
 *

bool qi::os::fnmatch	(	const std::string &	pattern,
		const std::string &	string
	)

handles * and ? wilcards

qi::os::fopen	(	const char *	filename,
		const char *	mode
	)

Open a file and returns and handle on it.

Parameters:

filename	Path to the file (in UTF-8).
mode	The mode.

Returns:: A FILE* handle if successful, 0 on error.

 * Nothing special under POSIX systems, it's only useful for Windows,
 * where files should be open using a widestring.
 *
 * Refer to ``man 3 fopen`` for more informations on POSIX systems, and to the
 * documentation of _wfopen on MSDN to understand the Windows behaviors.
 *
 * .. versionadded:: 1.12
 *

qi::os::generateUuid ( )

Generate a universally unique identifier.

Returns:: The uuid. .. versionadded:: 1.20

qi::os::getenv ( const char * var )

Get an environment variable.

Parameters:

var	The environment variable to search for.

Returns:: The value in the environment, or an empty string if there is no match.

 * Searches the  environment list to find the environment variable var, and
 * returns a pointer to the corresponding value string.
 *
 * .. versionadded:: 1.12
 *

qi::os::gethostname ( )

Get the system's hostname.

Returns:: The system's hostname. An empty string is returned on failure.

qi::os::getMachineId ( )

Returns an unique uuid for the machine.

Returns:: The uuid of the machine.

The UUID is stored on disk and will stay unchanged as long as it is not removed. All programs running on the same machine will have the same UUID returned. An empty string is returned on failure.

qi::os::getpid ( )

Get the process identifier.

qi::os::gettid ( )

Get the thread identifier.

qi::os::gettimeofday ( qi::os::timeval * tp )

The gettimeofday() function shall obtain the current time.

Parameters:

tp	The timeval structure used to return the current time.

Returns:: 0 on success

The gettimeofday() function shall obtain the current time, expressed as seconds and microseconds since the Epoch, and store it in the timeval structure pointed to by tp. The resolution of the system clock is unspecified. This clock is subject to NTP adjustments.

qi::os::home ( )

Return path to the current user's HOME.

qi::os::hostIPAddrs ( bool ipv6Addr = false )

Find all network adapters and corresponding IPs.

Parameters:

ipv6Addr Look for IPv6 addresses instead of IPv4 ones.

Returns:: A map of interfaces associated with the list of IPs of that interface.

 * .. versionadded:: 1.14
 *

qi::os::isatty ( int fd = 1 )

Test if descriptor represents a terminal.

Returns:: Returns a value of 1 if the given file descriptor is a terminal. Otherwise returns a value of 0. By default test for stdout (1).

 * .. versionadded:: 1.22
 *

qi::os::kill	(	int	pid,
		int	sig
	)

Send a signal to a process.

Parameters:

pid	PID to kill.
sig	Signal to deliver to the process.

Returns:: See detailed description.

 * The kill() function shall send a signal to a process or a group of processes
 * specified by pid.
 *
 * Return value (rc):
 *
 * - rc = 0 means that everything went well.
 * - rc != 0 means that an error occurred. (For instance, no process
 *   corresponding to the pid was found).
 *
 * .. versionadded:: 1.14
 *

qi::os::memoryUsage ( unsigned int pid )

Get the memory usage of a process.

Parameters:

pid	PID of a process

Returns:: Returns a value > 0 corresponding to the memory in RAM used by the process in kB. Otherwise returns a value of 0, meaning that it was impossible to get the memory usage.

qi::os::mktmpdir ( const char * prefix = "" )

Return a writable temporary directory.

Parameters:

prefix Prefix of the tmp file (in UTF-8).

Returns:: The path to the temporary directory.

 * The caller is responsible for destroying the returned directory. This will
 * create a unique directory in the temporary directory returned by
 * :cpp:func:`qi::os::tmp()`.
 *
 * The specified prefix will be prepended to a uniquely generated name.
 *
 * .. versionadded:: 1.12.1
 *

qi::os::msleep ( unsigned int milliseconds )

Sleep for the specified number of milliseconds.

Parameters:

milliseconds Number of milliseconds to sleep.

 * Under Linux/OSX it will not be disturbed by eventual signals sent to process.
 * Makes the calling thread sleep until millliseconds have elapsed or a signal
 * which is not ignored arrives.
 *
 * .. seealso:: :cpp:func:`qi::os::sleep(unsigned int)`
 *
 * .. versionadded:: 1.12
 *

long qi::os::numberOfCPUs ( )

qi::os::timeval qi::os::operator+	(	const qi::os::timeval &	lhs,
		const qi::os::timeval &	rhs
	)

qi::os::timeval qi::os::operator+	(	const qi::os::timeval &	lhs,
		long	us
	)

qi::os::timeval qi::os::operator-	(	const qi::os::timeval &	lhs,
		const qi::os::timeval &	rhs
	)

qi::os::timeval qi::os::operator-	(	const qi::os::timeval &	lhs,
		long	us
	)

bool qi::os::setCurrentThreadCPUAffinity ( const std::vector< int > & cpus )

qi::os::setCurrentThreadName ( const std::string & name )

Set the current thread name to the string in parameter.

Parameters:

name	The new name of the current thread.

qi::os::setenv	(	const char *	var,
		const char *	value
	)

Change or add an environment variable.

Parameters:

var	The variable name.
value	The value of the variable.

Returns:: 0 on success, or -1 on error.

 * Adds the variable name to the environment with the value in argument if name
 * does not already exist. Else changes its value.
 *
 * .. versionadded:: 1.12
 *

qi::os::sleep ( unsigned int seconds )

Sleep for the specified number of seconds.

Parameters:

seconds Number of seconds to sleep.

 * Under Linux/OS X it will not be disturbed by eventual signals. Makes the
 * calling thread sleep until seconds have elapsed or a signal arrives which
 * is not ignored.
 *
 * .. todo::
 *     Explain the behavior of signals on windows when sleeping.
 *
 * .. seealso:: :cpp:func:`qi::os::msleep(unsigned int)`
 *
 * .. versionadded:: 1.12
 *

qi::os::snprintf	(	char *	str,
		size_t	size,
		const char *	format,
			...
	)

Implement POSIX compliant snprintf.

 * .. seealso:: http://en.cppreference.com/w/cpp/io/c/fprintf
 *

qi::os::spawnlp	(	const char *	argv,
			...
	)

Create and execute a new process.

Parameters:

argv	Path to the file to be executed.
...	The command line arguments of the new process as var args.

Returns:: -1 on error, child pid otherwise.

 * Creates and executes a new process.
 *
 * .. versionadded:: 1.12
 *

qi::os::spawnvp ( char *const argv[] )

Create and execute a new process.

Parameters:

argv	The command line arguments of the new process as an array (NULL terminated).

Returns:: -1 on error, child pid otherwise.

 * Creates and executes a new process.
 *
 * .. versionadded:: 1.12
 *

qi::os::stat	(	const char *	filename,
		struct stat *	pstat
	)

Get file status.

Parameters:

filename	Path to the file (in UTF-8).
pstat	A pointer to a stat structure that will be filled by the function.

Returns:: 0 on success, -1 on error

 * Stats the file pointed to by filename and fills in pstat.
 * You need to include <sys/stat.h> to get access to struct.
 *
 * .. todo::
 *     explain how to use stat on windows !
 *
 * .. versionadded:: 1.12
 *

char* qi::os::strdup ( const char * src )

int qi::os::system ( const char * command )

Execute a shell command.

Parameters:

command Command to execute.

Returns:: The value returned is -1 on error, and the return status of the command otherwise.

 * Executes a command by calling ``/bin/sh -c command``, and returns when the
 * command has completed.
 *
 * .. versionadded:: 1.12
 *

qi::os::timezone ( )

Return the timezone.

Returns:: A string with the timezone.

 * .. versionadded:: 1.22
 *

qi::os::tmp ( )

Return the system's temporary directory.

Returns:: The path to the system's temporary directory.

The directory is writable and exists. The caller is responsible for destroying the temporary files it creates.

qi::os::tmpdir ( const char * prefix = "" )

Return a temporary directory.

Parameters:

prefix Prefix of the tmp file (in UTF-8).

Returns:: The path to the temporary directory.

 * Look at :cpp:func:`qi::os::mktmpdir(const char*)`
 *
 * .. deprecated:: 1.12.1
 *

qi::os::ustime ( )

Return elapsed time since program started in microseconds.

qi::os::waitpid	(	int	pid,
		int *	status
	)

Wait for process to change state.

Parameters:

pid	Pid to wait.
status	Status returned by the process.

Returns:: See detailed description.

 * Suspends execution of the calling process until a child specified by pid
 * argument changes of state.
 *
 * Return values (rc):
 *
 * - rc = 0 means that everything went well.
 * - rc > 0 means that an error occurred. (For instance, no process
 *   corresponding to the pid was found). The exact value is an errno code.
 * - rc < 0 means that the child was killed by a signal. The value of the signal
 *   is -rc.
 *
 * .. versionadded:: 1.12
 *

Classes

Functions

Detailed Description

Function Documentation