4.14. Platform abstraction functions — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# 4.14. Platform abstraction functions

The `platform` sub-namespace inside the `LAMMPS_NS` namespace provides a collection of wrapper and convenience functions and utilities that perform common tasks for which platform specific code would be required or for which a more high-level abstraction would be convenient and reduce duplicated code. This reduces redundant implementations and encourages consistent behavior and thus has some overlap with the “utils” sub-namespace.

## 4.14.1. Time functions

double LAMMPS_NS:: platform:: cputime()

  Return the consumed CPU time for the current process in seconds

  This is a wrapper around the POSIX function getrusage() and its Windows equivalent. It is to be used in a similar fashion as MPI_Wtime(). Its resolution may be rather low so it can only be trusted when observing processes consuming CPU time of at least a few seconds.

  Returns:

    used CPU time in seconds

double LAMMPS_NS:: platform:: walltime()

  Return the wall clock state for the current process in seconds

  This clock is counting continuous time and is initialized during load of the executable/library. Its absolute value must be considered arbitrary and thus elapsed wall times are measured in taking differences. It is therefore to be used in a similar fashion as MPI_Wtime() but has a different offset, usually leading to better resolution.

  Returns:

    wall clock time in seconds

void LAMMPS_NS:: platform:: usleep(int usec)

  Suspend execution for a microsecond interval

  This emulates the usleep(3) BSD function call also mentioned in POSIX.1-2001. This is not a precise delay; it may be longer, but not shorter.

  Parameters:

    usec – length of delay in microseconds

## 4.14.2. Platform information functions

std:: string LAMMPS_NS:: platform:: os_info()

  Return string with the operating system version and architecture info

  Returns:

    string with info about the OS and the platform is is running on

std:: string LAMMPS_NS:: platform:: compiler_info()

  Return string with compiler version info

  This function uses predefined compiler macros to identify Compilers and their version and configuration info.

  Returns:

    string with the compiler information text

std:: string LAMMPS_NS:: platform:: cxx_standard()

  Return string with C++ standard version used to compile LAMMPS.

  This function uses predefined compiler macros to identify the C++ standard version used to compile LAMMPS with.

  Returns:

    string with the C++ standard version or “unknown”

std:: string LAMMPS_NS:: platform:: openmp_standard()

  Return string with OpenMP standard version info

  This function uses predefined compiler macros to identify OpenMP support and the supported version of the standard.

  Returns:

    string with the openmp information text

std:: string LAMMPS_NS:: platform:: mpi_vendor()

  Return string with MPI vendor info

  This function uses predefined macros to identify the vendor of the MPI library used.

  Returns:

    string with the MPI vendor information text

std:: string LAMMPS_NS:: platform:: mpi_info(int &major, int &minor)

  Return string with MPI version info

  This function uses predefined macros and MPI function calls to identify the version of the MPI library used.

  Parameters:

    - major – major version of the MPI standard (set on exit)

    - minor – minor version of the MPI standard (set on exit)

  Returns:

    string with the MPI version information text

std:: string LAMMPS_NS:: platform:: compress_info()

  Return string with list of available compression types and executables

  This function tests which of the supported compression executables are available for reading or writing compressed files where supported.

  Returns:

    string with list of available compression tools

## 4.14.3. File and path functions and global constants

constexpr char LAMMPS_NS:: platform:: filepathsep[] = "/"

  Platform specific file path component separator

  This is a string with the character that separates directories and filename in paths on a platform. If multiple are characters are provided, the first is the preferred one.

constexpr char LAMMPS_NS:: platform:: pathvarsep = ':'

  Platform specific path environment variable component separator

  This is the character that separates entries in “PATH”-style environment variables.

const char *LAMMPS_NS:: platform:: guesspath(FILE *fp, char *buf, int len)

  Try to detect pathname from FILE pointer

  Currently only supported on Linux, MacOS, and Windows. Otherwise will report “(unknown)”.

  On Linux the folder /proc/self/fd holds symbolic links to the actual pathnames associated with each open file descriptor of the current process. On MacOS the same kind of information can be obtained using `fcntl(fd,F_GETPATH,buf)`. On Windows we use `GetFinalPathNameByHandleA()` which is available with Windows Vista and later. If the buffer is too small (< 16 bytes) a null pointer is returned.

  This function is used to provide a filename with error messages in functions where the filename is not passed as an argument, but the FILE * pointer.

  Parameters:

    - fp – FILE pointer struct from STDIO library for which we want to detect the name

    - buf – storage buffer for pathname. output will be truncated if not large enough

    - len – size of storage buffer. output will be truncated to this length - 1

  Returns:

    pointer to the storage buffer with path or a NULL pointer if buf is invalid or the buffer size is too small

std:: string LAMMPS_NS:: platform:: path_basename(const std:: string &path)

  Strip off leading part of path, return just the filename

  Parameters:

    path – file path

  Returns:

    file name

std:: string LAMMPS_NS:: platform:: path_join(const std:: string &a, const std:: string &b)

  Join two pathname segments

  This uses the forward slash ‘/’ character unless LAMMPS is compiled for Windows where it uses the backward slash ‘'

  Parameters:

    - a – first path

    - b – second path

  Returns:

    combined path

bool LAMMPS_NS:: platform:: file_is_readable(const std:: string &path)

  Check if file exists and is readable

  Parameters:

    path – file path

  Returns:

    true if file exists and is readable

bool LAMMPS_NS:: platform:: is_console(FILE *fp)

  Check if a file pointer may be connected to a console

  Parameters:

    fp – file pointer

  Returns:

    true if the file pointer is flagged as a TTY

double LAMMPS_NS:: platform:: disk_free(const std:: string &path)

  Return free disk space in bytes of file system pointed to by path

  Returns -1.0 if the path is invalid or free space reporting not supported.

  Parameters:

    path – file or folder path in file system

  Returns:

bool LAMMPS_NS:: platform:: path_is_directory(const std:: string &path)

  Check if a path is a directory

  Parameters:

    path – directory path

  Returns:

    true if the directory exists

std:: string LAMMPS_NS:: platform:: current_directory()

  Get string with path to the current directory

  Returns:

    path to the current directory or empty string

std:: vector<std:: string> LAMMPS_NS:: platform:: list_directory(const std:: string &dir)

  Get list of entries in a directory

  This provides a list of strings of the entries in the directory without the leading path name while also skipping over “..” and “.”.

  Parameters:

    dir – path to directory

  Returns:

    vector with strings of all directory entries

int LAMMPS_NS:: platform:: chdir(const std:: string &path)

  Change current directory

  Parameters:

    path – new current working directory path

  Returns:

    -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS:: platform:: mkdir(const std:: string &path)

  Create a directory

  Unlike the the `mkdir()` or `_mkdir()` functions of the C library, this function will also try to create non-existing sub-directories in case they don’t exist, and thus behaves like the `mkdir -p` command rather than plain `mkdir` or ``md`.

  Parameters:

    path – directory path

  Returns:

    -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS:: platform:: rmdir(const std:: string &path)

  Delete a directory

  Unlike the the `rmdir()` or `_rmdir()` functions of the C library, this function will check for the contents of the folder and recurse into any sub-folders, if necessary, and delete all contained folders and their contents before deleting the folder path.

  Parameters:

    path – directory path

  Returns:

    -1 if unsuccessful, otherwise >= 0

int LAMMPS_NS:: platform:: unlink(const std:: string &path)

  Delete a file

  Parameters:

    path – path to file to be deleted

  Returns:

    0 on success, -1 on error

## 4.14.4. Standard I/O function wrappers

constexpr bigint LAMMPS_NS:: platform:: END_OF_FILE = -1

  constant to seek to the end of the file

bigint LAMMPS_NS:: platform:: ftell(FILE *fp)

  Get current file position

  Parameters:

    fp – FILE pointer of the given file

  Returns:

    current FILE pointer position cast to a bigint

int LAMMPS_NS:: platform:: fseek(FILE *fp, bigint pos)

  Set absolute file position

  If the absolute position is END_OF_FILE, then position at the end of the file.

  Parameters:

    - fp – FILE pointer of the given file

    - pos – new position of the FILE pointer

  Returns:

    0 if successful, otherwise -1

int LAMMPS_NS:: platform:: ftruncate(FILE *fp, bigint length)

  Truncate file to a given length and re-position file pointer

  Parameters:

    - fp – FILE pointer of the given file

    - length – length to which the file is being truncated to

  Returns:

    0 if successful, otherwise -1

FILE *LAMMPS_NS:: platform:: popen(const std:: string &cmd, const std:: string &mode)

  Open a pipe to a command for reading or writing

  Parameters:

    - cmd – command for the pipe

    - mode – “r” for reading from cmd or “w” for writing to cmd

  Returns:

    file pointer to the pipe if successful or null

int LAMMPS_NS:: platform:: pclose(FILE *fp)

  Close a previously opened pipe

  Parameters:

    fp – FILE pointer for the pipe

  Returns:

    exit status of the pipe command or -1 in case of errors

## 4.14.5. Environment variable functions

int LAMMPS_NS:: platform:: putenv(const std:: string &vardef)

  Add variable to the environment

  Parameters:

    vardef – variable name or variable definition (NAME=value)

  Returns:

    -1 if failure otherwise 0

int LAMMPS_NS:: platform:: unsetenv(const std:: string &variable)

  Delete variable from the environment

  Parameters:

    variable – variable name

  Returns:

    -1 if failure otherwise 0

std:: vector<std:: string> LAMMPS_NS:: platform:: list_pathenv(const std:: string &var)

  Get list of entries in a path environment variable

  This provides a list of strings of the entries in an environment variable that is containing a “path” like “PATH” or “LD_LIBRARY_PATH”.

  Parameters:

    var – name of the environment variable

  Returns:

    vector with strings of all entries in that path variable

std:: string LAMMPS_NS:: platform:: find_exe_path(const std:: string &cmd)

  Find pathname of an executable in the standard search path

  This function will traverse the list of directories in the PATH environment variable and look for the executable cmd. If the file exists and is executable the full path is returned as string, otherwise an empty string is returned.

  On Windows the cmd string must not include an extension as this function will automatically append the extensions “.exe”, “.com” and “.bat” and look for those paths. On Windows also the current directory is checked (and first), but otherwise is not checked unless “.” exists in the PATH environment variable.

  Because of the nature of the check, this will not detect shell functions built-in command or aliases.

  Parameters:

    cmd – name of command

  Returns:

    vector with strings of all directory entries

## 4.14.6. Dynamically loaded object or library functions

void *LAMMPS_NS:: platform:: dlopen(const std:: string &fname)

  Open a shared object file or library

  Parameters:

    fname – name or path of the shared object

  Returns:

    handle to the shared object or null

int LAMMPS_NS:: platform:: dlclose(void *handle)

  Close a shared object

  This releases the object corresponding to the provided handle. Resolved symbols associated with this handle may not be used after this call

  Parameters:

    handle – handle to an opened shared object

  Returns:

    0 if successful, non-zero of not

void *LAMMPS_NS:: platform:: dlsym(void *handle, const std:: string &symbol)

  Resolve a symbol in shared object

  Parameters:

    - handle – handle to an opened shared object

    - symbol – name of the symbol to extract

  Returns:

    pointer to the resolved symbol or null

std:: string LAMMPS_NS:: platform:: dlerror()

  Obtain error diagnostic info after dynamic linking function calls

  Return a human-readable string describing the most recent error that occurred when using one of the functions for dynamic loading objects the last call to this function. If there was no error, the string is empty.

  Returns:

    string with error message or empty

## 4.14.7. Compressed file I/O functions

bool LAMMPS_NS:: platform:: has_compress_extension(const std:: string &file)

  Check if a file name ends in a known extension for a compressed file format

  Currently supported file extensions are: .gz, .bz2, .zst, .xz, .lzma, lz4

  Parameters:

    file – name of the file to check

  Returns:

    true if the file has a known extension, otherwise false

FILE *LAMMPS_NS:: platform:: compressed_read(const std:: string &file)

  Open pipe to compressed text file for reading

  Parameters:

    file – name of the file to open

  Returns:

    FILE pointer to pipe using for reading the compressed file.

FILE *LAMMPS_NS:: platform:: compressed_write(const std:: string &file)

  Open pipe to compressed text file for writing

  Parameters:

    file – name of the file to open

  Returns:

    FILE pointer to pipe using for reading the compressed file.