cross-platform os related function. (mostly following POSIX convention)
More...

Namespaces
namespace	qi::os
	OS abstraction layer.

Classes
struct	qi::os::timeval
	qi::os::timeval struct similar to POSIX timeval More...

Functions
QI_API FILE *	qi::os::fopen (const char filename, const char mode)
	Open a file.
QI_API int	qi::os::stat (const char filename, struct stat pstat)
	Get file status.
QI_API int	qi::os::checkdbg ()
	Check if the current program is running under a debugger.
QI_API std::string	qi::os::home ()
	Return path to the current user's HOME.
QI_API std::string	qi::os::mktmpdir (const char *prefix="")
	Return a writable temporary directory. The caller is responsible of destroying the returned directory. This will create a unique directory in the temporary directory returned by qi::os::tmp(). The specified prefix will be prefixed to a generated unique name. .
QI_API_DEPRECATED QI_API std::string	qi::os::tmpdir (const char *prefix="")
	Return a temporary directory. look at qi::os::mktmpdir .
QI_API std::string	qi::os::tmp ()
	Return the system's temporary directory. The directory is writeable and exits. The caller is responsible of destroying the temporary file create. .
QI_API std::string	qi::os::gethostname ()
	Get the system's hostname. An empty string is returned on failure. .

Environment Functions
QI_API std::string	qi::os::getenv (const char *var)
	Get an environment variable.
QI_API int	qi::os::setenv (const char var, const char value)
	Change or add an environment variable.

Time Functions
QI_API void	qi::os::sleep (unsigned int seconds)
	Sleep for the specified number of seconds.
QI_API void	qi::os::msleep (unsigned int milliseconds)
	Sleep for the specified number of milliseconds.
QI_API int	qi::os::gettimeofday (qi::os::timeval *tp)
	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.

Shared Library Functions
QI_API void *	qi::os::dlopen (const char *filename, int flag=-1)
	Loads dynamic library.
QI_API int	qi::os::dlclose (void *handle)
	Decrements the reference count on the dynamic library.
QI_API void *	qi::os::dlsym (void handle, const char symbol)
	Get the address where the symbol is loaded into memory.
QI_API const char *	qi::os::dlerror (void)
	Returns a human readable string.

Process Functions
QI_API int	qi::os::spawnvp (char *const argv[])
	Create and execute a new process.
QI_API int	qi::os::spawnlp (const char *argv,...)
	Create and execute a new process.
QI_API int	qi::os::system (const char *command)
	Execute a shell command.
QI_API int	qi::os::waitpid (int pid, int *status)
	Wait for process to change state.
QI_API unsigned short	qi::os::findAvailablePort (unsigned short port)
	Find the first available port starting at `port`.

Detailed Description

cross-platform os related function. (mostly following POSIX convention)

#include <qi/os.hpp>

Include POSIX compatibility support for OS not following POSIX. This namespace provide abstracted OS functions working on three operatrion system (Linux, MacOS, Windows) with the same behavior.

Warning:: Every string MUST be encoded in UTF8 and return UTF-8.

Features:

change environment variables (qi::os::setenv, qi::os::getenv)
loading shared libraries (qi::os::dlopen, qi::os::dlsym, qi::os::dyerror, qi::os::dlclose)
file operations (qi::os::fopen, qi::os::stat)
manage processes (qi::os::spawnvp, qi::os::spawnlp, qi::os::system, qi::os::wait)
time (qi::os::sleep, qi::os::msleep, qi::gettimeofday)

Function Documentation

qi::os::checkdbg ( )

Check if the current program is running under a debugger.

Warning:: Not implement for windows.

Returns:: -1 on error, 1 if the program is currently being debugged, 0 otherwize.

Since:: 1.12

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

Decrements the reference count on the dynamic library.

Decrements the reference count on the dynamic library handle. If the reference count drops to zero and no other loaded libraries use symbols in it, then the dynamic library is unloaded.

Parameters:

handle The dynamic library handle.

Returns:: 0 on success, and nonzero on error.

Since:: 1.12

See also:: qi::os::dlopen qi::os::dlsym qi::os::dlerror

const char * qi::os::dlerror ( void )

Returns a human readable string.

Returns a human readable string describing the most recent error that occurred from dlopen(), dlsym() or dlclose() since the last call to dlerror().

Returns:: It returns NULL if no errors have occurred since initialization or since it was last called or the human readable string.

Since:: 1.12

See also:: qi::os::dlopen qi::os::dlsym qi::os::dlclose

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

Loads dynamic library.

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.

Parameters:

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

Since:: 1.12

See also:: qi::os::dlsym qi::os::dlerror qi::os::dlclose

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

Get the address where the symbol is loaded into memory.

If the symbol is not found, in the specified library or any of the libraries that were automatically loaded by dlopen() when that library was loaded, dlsym() returns NULL.

Parameters:

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

Since:: 1.12

See also:: qi::os::dlopen qi::os::dlerror qi::os::dlclose

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

Find the first available port starting at port.

Parameters:

port	First port tested, then try each port after this one one by one.

Returns:: Available port or 0 on error

Since:: 1.14

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

Open a file.

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, and to the documentation of _wfopen on MSDN to understand the Windows behaviors.

Parameters:

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

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

Since:: 1.12

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

Get an environment variable.

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

Parameters:

var	The environment variable to search for.

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

Since:: 1.12

See also:: qi::os::setenv

std::string qi::os::gethostname ( )

Get the system's hostname.

    An empty string is returned on failure.

.

Returns:: The system's hostname

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

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.

Parameters:

tp	the timeval structure used to return the current time

Returns:: should return 0 on success

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

Return a writable temporary directory.

     The caller is responsible of destroying the returned directory.
     This will create a unique directory in the temporary directory returned by qi::os::tmp().
     The specified prefix will be prefixed to a generated unique name.

.

Parameters:

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

Since:: 1.12.1

Returns:: The path to the temporary directory.

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

Sleep for the specified number of milliseconds.

Under Linux/OSX it will not be disturbed by eventual signals. Makes the calling thread sleep until millliseconds have elapsed or a signal arrives which is not ignored.

Parameters:

milliseconds Number of milliseconds to sleep for

Since:: 1.12

See also:: qi::os::sleep

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

Change or add an environment variable.

Adds the variable name to the environment with the value var, if name does not already exist. If var does exist in the environment, then its value is changed to value

Parameters:

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

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

Since:: 1.12

See also:: qi::os::getenv

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

Sleep for the specified number of seconds.

Under Linux/OSX 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.

Parameters:

seconds Number of second to sleep for

Since:: 1.12

See also:: qi::os::msleep

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

Create and execute a new process.

Creates and executes a new process

Parameters:

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

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

Since:: 1.12

See also:: qi::os::waitpid qi::os::spawnvp qi::os::system

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

Create and execute a new process.

Creates and executes 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.

Since:: 1.12

See also:: qi::os::waitpid qi::os::spawnlp qi::os::system

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

Get file status.

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 !

Parameters:

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

Returns:: 0 on success, -1 on error

Since:: 1.12

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

Execute a shell command.

Executes a command specified in command by calling /bin/sh -c command, and returns after the command has been completed.

Parameters:

command Command to execute.

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

Since:: 1.12

See also:: qi::os::spawnlp qi::os::spawnvp

std::string qi::os::tmp ( )

Return the system's temporary directory.

     The directory is writeable and exits.
     The caller is responsible of destroying the temporary
     file create.

.

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

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

Return a temporary directory.

     look at qi::os::mktmpdir

.

Parameters:

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

Deprecated:: 1.12.1

Returns:: The path to the temporary directory.

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

Wait for process to change state.

Suspends execution of the calling process until a child specified by pid argument has changed state.

Parameters:

pid	Pid to wait
status	Pointer to a buffer where the return code of the specified process will be stored, or NULL.

Returns:: rc. rc = 0 means that everything went well. rc > 0 means that an error occurs. (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.

Since:: 1.12

See also:: qi::os::spawnlp qi::os::spawnvp

Namespaces

Classes

Functions

Environment Functions

Time Functions

Shared Library Functions

Process Functions

Detailed Description

Function Documentation