libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Functions
qi::os Namespace Reference

OS abstraction layer. . More...

Classes

struct  timeval
 struct similar to POSIX timeval More...
 
class  ScopedThreadName
 Set the current thread name and restore it after use. More...
 

Functions

template<typename T >
getEnvDefault (const char *name, T defaultVal)
 
FILE * fopen (const char *filename, const char *mode)
 Open a file and returns and handle on it. More...
 
int stat (const char *filename, struct stat *pstat)
 Get file status. More...
 
int checkdbg ()
 Check if the current process is running into a debugger. More...
 
std::string home ()
 Return path to the current user's HOME. More...
 
std::string mktmpdir (const char *prefix="")
 Return a writable temporary directory. More...
 
std::string tmp ()
 Return the system's temporary directory. More...
 
void symlink (const qi::Path &source, const qi::Path &destination)
 Create a symlink from source to destination. More...
 
std::string gethostname ()
 Get the system's hostname. More...
 
int isatty (int fd=1)
 Test if descriptor represents a terminal. More...
 
bool fnmatch (const std::string &pattern, const std::string &string)
 Implement POSIX compliant fnmatch. More...
 
char * strdup (const char *src)
 Implement POSIX compliant strdup. More...
 
int snprintf (char *str, size_t size, const char *format,...)
 Implement POSIX compliant snprintf. More...
 
std::string getenv (const char *var)
 Get an environment variable. More...
 
std::string pathsep ()
 Get the path separator. More...
 
int setenv (const char *var, const char *value)
 Change or add an environment variable. More...
 
int unsetenv (const char *var)
 Remove an environment variable. More...
 
std::string timezone ()
 Return the timezone. More...
 
void sleep (unsigned int seconds)
 Sleep for the specified number of seconds. More...
 
void msleep (unsigned int milliseconds)
 Sleep for the specified number of milliseconds. More...
 
QI_API_DEPRECATED int gettimeofday (qi::os::timeval *tp)
 The gettimeofday() function shall obtain the current time. More...
 
qi::int64_t ustime ()
 Elapsed time since program started in microseconds. More...
 
std::pair< int64_t, int64_tcputime ()
 Return CPU time used by the calling thread as a pair (userTime, systemTime) in microseconds. More...
 
qi::os::timeval operator+ (const qi::os::timeval &lhs, const qi::os::timeval &rhs)
 Add two timeval together. More...
 
qi::os::timeval operator+ (const qi::os::timeval &lhs, long us)
 Add a delay to a timeval (in microsecond) More...
 
qi::os::timeval operator- (const qi::os::timeval &lhs, const qi::os::timeval &rhs)
 Substract two timeval together. More...
 
qi::os::timeval operator- (const qi::os::timeval &lhs, long us)
 Substract a delay to a timeval (in microsecond) More...
 
void * dlopen (const char *filename, int flag=-1)
 Load a dynamic library. More...
 
int dlclose (void *handle)
 Decrements the reference count on the dynamic library. More...
 
void * dlsym (void *handle, const char *symbol)
 Get the address where the symbol is loaded into memory. More...
 
const char * dlerror ()
 Returns a human readable string of the error code. More...
 
int spawnvp (char *const argv[])
 Create and execute a new process. More...
 
int spawnlp (const char *argv,...)
 Create and execute a new process. More...
 
int system (const char *command)
 Execute a shell command. More...
 
int getpid ()
 Get the process identifier. More...
 
int gettid ()
 Get the thread identifier. More...
 
int waitpid (int pid, int *status)
 Wait for process to change state. More...
 
int kill (int pid, int sig)
 Send a signal to a process. More...
 
bool isProcessRunning (int pid, const std::string &fileName=std::string())
 Check whether a process is running, given its file name and pid. More...
 
unsigned short findAvailablePort (unsigned short port)
 Find the first available port starting at port number in parameter. More...
 
std::map< std::string,
std::vector< std::string > > 
hostIPAddrs (bool ipv6Addr=false)
 Find all network adapters and corresponding IPs. More...
 
void setCurrentThreadName (const std::string &name)
 Set the current thread name to the string in parameter. More...
 
std::string currentThreadName ()
 returns the current thread name as a std::string More...
 
bool setCurrentThreadCPUAffinity (const std::vector< int > &cpus)
 Set the CPU affinity for the current thread. More...
 
long numberOfCPUs ()
 Get the number of CPUs on the local machin. More...
 
std::string getMachineId ()
 Returns an unique uuid for the machine. More...
 
const UuidgetMachineIdAsUuid ()
 Same as getMachineId but return a uuid and not its string representation. More...
 
const UuidgetProcessUuid ()
 Returns an unique uuid for the process. More...
 
std::string generateUuid ()
 Generate a universally unique identifier. More...
 
size_t memoryUsage (unsigned int pid)
 Get the memory usage of a process in kB. More...
 
PtrUid ptrUid (void *address)
 
template<typename T >
getEnvParam (const char *name, T defaultVal)
 Returns the value of the environment variableif set, the defaultVal otherwise. More...
 
template<typename N >
std::string to_string (N n)
 (Arithmetic or Enum) N More...
 

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

Check if the current process is running into a debugger.

Returns
-1 on error, 1 if debugger is present, 0 otherwise
std::pair<int64_t, int64_t> qi::os::cputime ( )

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

Returns
Return 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.
std::string 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
int qi::os::dlclose ( void *  handle)

Decrements the reference count on the dynamic library.

Parameters
handleThe 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()` for more details on the error.
*
* .. versionadded:: 1.12
* 
const char* qi::os::dlerror ( )

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
* 
void* qi::os::dlopen ( const char *  filename,
int  flag = -1 
)

Load a dynamic library.

Parameters
filenameName of the dynamic library.
flagFlags 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()` for more details on the error.
*
* .. versionadded:: 1.12
* 
void* qi::os::dlsym ( void *  handle,
const char *  symbol 
)

Get the address where the symbol is loaded into memory.

Parameters
handleHandle on a dynamic library returned by dlopen().
symbolThe 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()` for more details on the error.
*
* .. versionadded:: 1.12
* 
unsigned short qi::os::findAvailablePort ( unsigned short  port)

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

Parameters
portFirst 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 
)

Implement POSIX compliant fnmatch.

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

Open a file and returns and handle on it.

Parameters
filenamePath to the file (in UTF-8).
modeThe 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
* 
std::string qi::os::generateUuid ( )

Generate a universally unique identifier.

Returns
The uuid. .. versionadded:: 1.20
std::string qi::os::getenv ( const char *  var)

Get an environment variable.

Parameters
varThe 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
* 
template<typename T >
T qi::os::getEnvDefault ( const char *  name,
defaultVal 
)

Definition at line 20 of file getenv.hpp.

template<typename T >
T qi::os::getEnvParam ( const char *  name,
defaultVal 
)
inline

Returns the value of the environment variableif set, the defaultVal otherwise.

Parameters
nameName of the environment variable
defaultValDefaultVal to return if the environment variable isn't set.
Returns
Function obtains the current value of the environment variable, name if set. Return defaultVal otherwise. .. versionadded:: 2.4

Definition at line 672 of file os.hpp.

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

Get the system's hostname.

Returns
The system's hostname. An empty string is returned on failure.
std::string 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.

const Uuid& qi::os::getMachineIdAsUuid ( )

Same as getMachineId but return a uuid and not its string representation.

int qi::os::getpid ( )

Get the process identifier.

const Uuid& qi::os::getProcessUuid ( )

Returns an unique uuid for the process.

Returns
The uuid of the process.
int qi::os::gettid ( )

Get the thread identifier.

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

The gettimeofday() function shall obtain the current time.

Parameters
tpThe timeval structure used to return the current time.
Returns
0 on success
Deprecated:
since 2.4. Use qi::SystemClock::now() instead.

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.

std::string qi::os::home ( )

Return path to the current user's HOME.

Returns
String to user's HOME
std::map<std::string, std::vector<std::string> > qi::os::hostIPAddrs ( bool  ipv6Addr = false)

Find all network adapters and corresponding IPs.

Parameters
ipv6AddrLook for IPv6 addresses instead of IPv4 ones.
Returns
A map of interfaces associated with the list of IPs of that interface.
* .. versionadded:: 1.14
* 
int qi::os::isatty ( int  fd = 1)

Test if descriptor represents a terminal.

Parameters
fdFile descriptor.
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
* 
bool qi::os::isProcessRunning ( int  pid,
const std::string &  fileName = std::string() 
)

Check whether a process is running, given its file name and pid.

Warning
On Linux, since the command line of the process takes a little time to be made available, the file name check may fail if the process was spawned too recently.
Parameters
pidThe PID to check.
fileNameThe name of the process: the executable file name with no .exe or _d.exe extension.
Returns
true if the process is running and has the expected name.
int qi::os::kill ( int  pid,
int  sig 
)

Send a signal to a process.

Parameters
pidPID to kill.
sigSignal 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
* 
size_t qi::os::memoryUsage ( unsigned int  pid)

Get the memory usage of a process in kB.

Parameters
pidPID 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.
std::string qi::os::mktmpdir ( const char *  prefix = "")

Return a writable temporary directory.

Parameters
prefixPrefix 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
* 
void qi::os::msleep ( unsigned int  milliseconds)

Sleep for the specified number of milliseconds.

Parameters
millisecondsNumber 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 ( )

Get the number of CPUs on the local machin.

Returns
Number of CPUs
qi::os::timeval qi::os::operator+ ( const qi::os::timeval lhs,
const qi::os::timeval rhs 
)

Add two timeval together.

Parameters
lhsFirst timeval
rhsSecond timeval
qi::os::timeval qi::os::operator+ ( const qi::os::timeval lhs,
long  us 
)

Add a delay to a timeval (in microsecond)

Parameters
lhsFrist timeval
usSecond timeval
qi::os::timeval qi::os::operator- ( const qi::os::timeval lhs,
const qi::os::timeval rhs 
)

Substract two timeval together.

Parameters
lhsFirst timeval
rhsSecond timeval
qi::os::timeval qi::os::operator- ( const qi::os::timeval lhs,
long  us 
)

Substract a delay to a timeval (in microsecond)

Parameters
lhsFrist timeval
usSecond timeval
std::string qi::os::pathsep ( )

Get the path separator.

Returns
The separator of paths.
* It is the separator we can found in PATH env for example.
* 
PtrUid qi::os::ptrUid ( void *  address)

Constructs a PtrUid using process and machine ids provided by qi::os implementation.

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

Set the CPU affinity for the current thread.

Parameters
cpusa vector of CPU core ids
Returns
true on success
Warning
This function has no effect under Android nor OSX.
* When CPU Affinity is set, the current thread will only be allowed
* to run on the given set of cores.
*
* .. versionadded:: 1.22
* 
void qi::os::setCurrentThreadName ( const std::string &  name)

Set the current thread name to the string in parameter.

Parameters
nameThe new name of the current thread.

Prefer using ScopedThreadName that will restore the thread name on exit.

Warning
this feature can be considered as slow and should only used when the task is long
int qi::os::setenv ( const char *  var,
const char *  value 
)

Change or add an environment variable.

Parameters
varThe variable name.
valueThe value of the variable.
Returns
0 on success, or another unspecified value on error, in which case errno is set to indicate the cause of the 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
* 
void qi::os::sleep ( unsigned int  seconds)

Sleep for the specified number of seconds.

Parameters
secondsNumber 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
* 
int 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
* 
int qi::os::spawnlp ( const char *  argv,
  ... 
)

Create and execute a new process.

Parameters
argvPath 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
* 
int qi::os::spawnvp ( char *const  argv[])

Create and execute a new process.

Parameters
argvThe 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
* 
int qi::os::stat ( const char *  filename,
struct stat *  pstat 
)

Get file status.

Parameters
filenamePath to the file (in UTF-8).
pstatA 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)

Implement POSIX compliant strdup.

void qi::os::symlink ( const qi::Path source,
const qi::Path destination 
)

Create a symlink from source to destination.

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

Execute a shell command.

Parameters
commandCommand 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
* 
std::string qi::os::timezone ( )

Return the timezone.

Returns
A string with the timezone.
* .. versionadded:: 1.22
* 
std::string 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.

template<typename N >
std::string qi::os::to_string ( n)

(Arithmetic or Enum) N

Definition at line 683 of file os.hpp.

int qi::os::unsetenv ( const char *  var)

Remove an environment variable.

Parameters
varThe variable name. If null, the behavior is unspecified.
Returns
0 on success, or another unspecified value on error, in which case errno is set to indicate the cause of the error.
* Removes the variable name from the environment. If the variable did not already exist or was
* unset, the environment is unchanged and the function returns with a success.
* 
Postcondition
getenv(var).empty()
qi::int64_t qi::os::ustime ( )

Elapsed time since program started in microseconds.

Returns
Return qi::int64_t in microseconds.
int qi::os::waitpid ( int  pid,
int *  status 
)

Wait for process to change state.

Parameters
pidPid to wait.
statusStatus 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
*