# SoftBank Robotics documentation What's new in NAOqi 2.8?

# qi::os

Basic OS abstracted functions.

## Summary

Global Namespaces

- namespace qi::os

  Functions (namespace qi::os)

  qi::os::mktmpdir

  qi::os::gethostname

  qi::os::kill

  qi::os::msleep

  qi::os::setCurrentThreadName

  qi::os::cputime

  qi::os::gettimeofday

  qi::os::dlerror

  qi::os::dlclose

  qi::os::getEnvParam

  qi::os::stat

  qi::os::operator-

  qi::os::operator+

  qi::os::getMachineIdAsUuid

  qi::os::getMachineId

  qi::os::getpid

  qi::os::setenv

  qi::os::setCurrentThreadCPUAffinity

  qi::os::pathsep

  qi::os::sleep

  qi::os::waitpid

  qi::os::numberOfCPUs

  qi::os::findAvailablePort

  qi::os::home

  qi::os::checkdbg

  qi::os::dlopen

  qi::os::dlsym

  qi::os::getProcessUuid

  qi::os::spawnvp

  qi::os::timezone

  qi::os::memoryUsage

  qi::os::symlink

  qi::os::gettid

  qi::os::generateUuid

  qi::os::spawnlp

  qi::os::unsetenv

  qi::os::strdup

  qi::os::fopen

  qi::os::to_string

  qi::os::tmp

  qi::os::fnmatch

  qi::os::isatty

  qi::os::hostIPAddrs

  qi::os::snprintf

  qi::os::getenv

  qi::os::currentThreadName

  qi::os::system

  qi::os::isProcessRunning

  qi::os::ustime

  qi::os::ptrUid

## Reference

### qi::os Namespace Reference

#### Introduction

OS abstraction layer. qi/os.hpp . `More...`

#### Inner Definitions

##### Classes

Name | Brief
--- | ---
`qi::os::timeval` | struct similar to POSIX timeval
`qi::os::ScopedThreadName` | Set the current thread name and restore it after use.

##### Functions

Name | Brief
--- | ---
`qi::os::getEnvDefault` |
`qi::os::fopen` | Open a file and returns and handle on it.
`qi::os::stat` | Get file status.
`qi::os::checkdbg` | Check if the current process is running into a debugger.
`qi::os::home` | Return path to the current user’s HOME.
`qi::os::mktmpdir` | Return a writable temporary directory.
`qi::os::tmp` | Return the system’s temporary directory.
`qi::os::symlink` | Create a symlink from source to destination.
`qi::os::gethostname` | Get the system’s hostname.
`qi::os::isatty` | Test if descriptor represents a terminal.
`qi::os::fnmatch` | Implement POSIX compliant fnmatch.
`qi::os::strdup` | Implement POSIX compliant strdup.
`qi::os::snprintf` | Implement POSIX compliant snprintf.
`qi::os::getenv` | Get an environment variable.
`qi::os::pathsep` | Get the path separator.
`qi::os::setenv` | Change or add an environment variable.
`qi::os::unsetenv` | Remove an environment variable.
`qi::os::timezone` | Return the timezone.
`qi::os::sleep` | Sleep for the specified number of seconds.
`qi::os::msleep` | Sleep for the specified number of milliseconds.
`qi::os::gettimeofday` | The gettimeofday() function shall obtain the current time.
`qi::os::ustime` | Elapsed time since program started in microseconds.
`qi::os::cputime` | Return CPU time used by the calling thread as a pair (userTime, systemTime) in microseconds.
`qi::os::operator+` | Add two timeval together.
`qi::os::operator+` | Add a delay to a timeval (in microsecond)
`qi::os::operator-` | Substract two timeval together.
`qi::os::operator-` | Substract a delay to a timeval (in microsecond)
`qi::os::dlopen` | Load a dynamic library.
`qi::os::dlclose` | Decrements the reference count on the dynamic library.
`qi::os::dlsym` | Get the address where the symbol is loaded into memory.
`qi::os::dlerror` | Returns a human readable string of the error code.
`qi::os::spawnvp` | Create and execute a new process.
`qi::os::spawnlp` | Create and execute a new process.
`qi::os::system` | Execute a shell command.
`qi::os::getpid` | Get the process identifier.
`qi::os::gettid` | Get the thread identifier.
`qi::os::waitpid` | Wait for process to change state.
`qi::os::kill` | Send a signal to a process.
`qi::os::isProcessRunning` | Check whether a process is running, given its file name and pid.
`qi::os::findAvailablePort` | Find the first available port starting at port number in parameter.
`qi::os::hostIPAddrs` | Find all network adapters and corresponding IPs.
`qi::os::setCurrentThreadName` | Set the current thread name to the string in parameter.
`qi::os::currentThreadName` | returns the current thread name as a std::string
`qi::os::setCurrentThreadCPUAffinity` | Set the CPU affinity for the current thread.
`qi::os::numberOfCPUs` | Get the number of CPUs on the local machin.
`qi::os::getMachineId` | Returns an unique uuid for the machine.
`qi::os::getMachineIdAsUuid` | Same as getMachineId but return a uuid and not its string representation.
`qi::os::getProcessUuid` | Returns an unique uuid for the process.
`qi::os::generateUuid` | Generate a universally unique identifier.
`qi::os::memoryUsage` | Get the memory usage of a process in kB.
`qi::os::ptrUid` |
`qi::os::getEnvParam` | Returns the value of the environment variableif set, the defaultVal otherwise.
`qi::os::to_string` | (Arithmetic or Enum) N

#### Detailed Description

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.

#### Functions

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

  Brief: 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.

  New in version 1.12.

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

  Brief: 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.

  New in version 1.12.

int `qi::os::``checkdbg`()

  Brief: Check if the current process is running into a debugger.

  Returns: | -1 on error, 1 if debugger is present, 0 otherwise

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

  Brief: Return path to the current user’s HOME.

  Returns: | String to user’s HOME

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

  Brief: 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 `qi::os::tmp()`.

  The specified prefix will be prepended to a uniquely generated name.

  New in version 1.12.1.

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

  Brief: 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.

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

  Create a symlink from source to destination.

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

  Brief: Get the system’s hostname.

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

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

  Brief: Test if descriptor represents a terminal.

  Parameters: | fd – File 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).

  New in version 1.22.

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

  Implement POSIX compliant fnmatch.

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

  Implement POSIX compliant strdup.

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

  See also

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

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

  Brief: 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.

  New in version 1.12.

std::string `qi::os::``pathsep`()

  Brief: Get the path separator.

  Returns: | The separator of paths.

  It is the separator we can found in PATH env for example.

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

  Brief: Change or add an environment variable.

  Parameters: | var – The variable name. value – The 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.

  New in version 1.12.

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

  Brief: Remove an environment variable.

  Parameters: | var – The 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.
  Post-condition: | getenv(var).empty()

  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.

std::string `qi::os::``timezone`()

  Brief: Return the timezone.

  Returns: | A string with the timezone.

  New in version 1.22.

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

  Brief: 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.

  See also

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

  New in version 1.12.

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

  Brief: 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.

  See also

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

  New in version 1.12.

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

  Brief: The gettimeofday() function shall obtain the current time.

  Parameters: | tp – The timeval structure used to return the current time.
  Returns: | 0 on success

  Deprecatedsince 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.

qi::int64_t `qi::os::``ustime`()

  Brief: Elapsed time since program started in microseconds.

  Returns: | Return qi::int64_t in microseconds.

std::pair<int64_t, int64_t> `qi::os::``cputime`()

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

  Returns: | Return pair(userTime, systemTime) in microseconds.

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

  Brief: Add two timeval together.

  Parameters: | lhs – First timeval rhs – Second timeval

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

  Brief: Add a delay to a timeval (in microsecond)

  Parameters: | lhs – Frist timeval us – Second timeval

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

  Brief: Substract two timeval together.

  Parameters: | lhs – First timeval rhs – Second timeval

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

  Brief: Substract a delay to a timeval (in microsecond)

  Parameters: | lhs – Frist timeval us – Second timeval

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

  Brief: 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.

  See also

  `qi::os::dlerror()` for more details on the error.

  New in version 1.12.

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

  Brief: 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.

  See also

  `qi::os::dlerror()` for more details on the error.

  New in version 1.12.

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

  Brief: 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 `qi::os::dlopen()` when that library was loaded, `qi::os::dlsym()` returns 0.

  See also

  `qi::os::dlerror()` for more details on the error.

  New in version 1.12.

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

  Brief: 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 `qi::os::dlopen(const char*, int)`, `qi::os::dlsym(void*, const char*)` or `qi::os::dlclose(void*)` since the last call to `qi::os::dlerror()`.

  New in version 1.12.

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

  Brief: 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.

  New in version 1.12.

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

  Brief: 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.

  New in version 1.12.

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

  Brief: 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.

  New in version 1.12.

int `qi::os::``getpid`()

  Get the process identifier.

int `qi::os::``gettid`()

  Get the thread identifier.

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

  Brief: 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.

  New in version 1.12.

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

  Brief: 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).

  New in version 1.14.

bool `qi::os::``isProcessRunning`(int pid, const std::string& fileName = std::string()

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

  Parameters: | pid – The PID to check. fileName – The 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.

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

  Brief: 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.

  New in version 1.14.

std::map<std::string, std::vector<std::string>> `qi::os::``hostIPAddrs`(bool ipv6Addr = false)

  Brief: 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.

  New in version 1.14.

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

  Brief: Set the current thread name to the string in parameter.

  Parameters: | name – The new name of the current thread.

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

std::string `qi::os::``currentThreadName`()

  Brief: returns the current thread name as a std::string

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

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

  Brief: Set the CPU affinity for the current thread.

  Parameters: | cpus – a vector of CPU core ids
  Returns: | true on success

  When CPU Affinity is set, the current thread will only be allowed to run on the given set of cores.

  New in version 1.22.

long `qi::os::``numberOfCPUs`()

  Brief: Get the number of CPUs on the local machin.

  Returns: | Number of CPUs

std::string `qi::os::``getMachineId`()

  Brief: 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.

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

  Brief: Returns an unique uuid for the process.

  Returns: | The uuid of the process.

std::string `qi::os::``generateUuid`()

  Brief: Generate a universally unique identifier.

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

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

  Brief: Get the memory usage of a process in kB.

  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.

PtrUid `qi::os::``ptrUid`(void* address)

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

template<typename T>

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

Parameters: | name -- Name of the environment variable defaultVal -- DefaultVal 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

T `qi::os::``getEnvParam`(const char* name, T defaultVal)

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

  (Arithmetic or Enum) N

Glossary Site map Index Support Contact Legal Notices