libqi  1.14
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Namespaces | Classes | Functions
qi::os

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:


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:
handleThe 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:
filenameName of the dynamic library.
flagFlags 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:
handleHandle of a dynamic library returned by dlopen().
symbolThe 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:
portFirst 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:
filenamePath to the file (in UTF-8).
modeThe 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:
varThe 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:
tpthe 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:
prefixPrefix 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:
millisecondsNumber 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:
varThe variable name.
valueThe 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:
secondsNumber 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:
argvPath 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:
argvThe 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:
filenamePath to the file (in UTF-8).
pstatA 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:
commandCommand 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:
prefixPrefix 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:
pidPid to wait
statusPointer 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