:orphan: .. index:: pair: group; Processes configuration .. _doxid-group__tapi__conf__process: Processes configuration ======================= .. toctree:: :hidden: enum_tapi_cfg_ps_exit_status_type_t.rst struct_tapi_cfg_ps_exit_status_t.rst Overview ~~~~~~~~ Definition of TAPI to configure processes. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef enum :ref:`tapi_cfg_ps_exit_status_type_t` :ref:`tapi_cfg_ps_exit_status_type_t`; typedef struct :ref:`tapi_cfg_ps_exit_status_t` :ref:`tapi_cfg_ps_exit_status_t`; // enums enum :ref:`tapi_cfg_ps_exit_status_type_t`; // structs struct :ref:`tapi_cfg_ps_exit_status_t`; // global functions :ref:`te_errno` :ref:`tapi_cfg_ps_add`(const char* ta, const char* ps_name, const char* exe, bool start); :ref:`te_errno` :ref:`tapi_cfg_ps_del`(const char* ta, const char* ps_name); :ref:`te_errno` :ref:`tapi_cfg_ps_start`(const char* ta, const char* ps_name); :ref:`te_errno` :ref:`tapi_cfg_ps_stop`(const char* ta, const char* ps_name); :ref:`te_errno` :ref:`tapi_cfg_ps_get_status`(const char* ta, const char* ps_name, bool* status); :ref:`te_errno` :ref:`tapi_cfg_ps_add_arg`(const char* ta, const char* ps_name, unsigned int order, const char* arg); :ref:`te_errno` :ref:`tapi_cfg_ps_add_env`(const char* ta, const char* ps_name, const char* env_name, const char* value); :ref:`te_errno` :ref:`tapi_cfg_ps_add_opt`(const char* ta, const char* ps_name, const char* opt_name, const char* value); :ref:`te_errno` :ref:`tapi_cfg_ps_set_long_opt_sep`(const char* ta, const char* ps_name, const char* value); :ref:`te_errno` :ref:`tapi_cfg_ps_set_autorestart`(const char* ta, const char* ps_name, unsigned int value); :ref:`te_errno` :ref:`tapi_cfg_ps_get_autorestart`(const char* ta, const char* ps_name, unsigned int* value); :ref:`te_errno` :ref:`tapi_cfg_ps_set_workdir`(const char* ta, const char* ps_name, const char* workdir); :ref:`te_errno` :ref:`tapi_cfg_ps_get_workdir`(const char* ta, const char* ps_name, char** workdir); :ref:`te_errno` :ref:`tapi_cfg_ps_kill`(const char* ta, const char* ps_name, int signo); :ref:`te_errno` :ref:`tapi_cfg_ps_killpg`(const char* ta, const char* ps_name, int signo); :ref:`te_errno` :ref:`tapi_cfg_ps_wait`(const char* ta, const char* ps_name, int timeout_ms, :ref:`tapi_cfg_ps_exit_status_t`* exit_status); .. _details-group__tapi__conf__process: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Definition of TAPI to configure processes. Copyright (C) 2020-2022 OKTET Labs Ltd. All rights reserved. Typedefs -------- .. index:: pair: typedef; tapi_cfg_ps_exit_status_type_t .. _doxid-group__tapi__conf__process_1ga917c2f415d306cef091b32fd61d7b535: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_cfg_ps_exit_status_type_t` tapi_cfg_ps_exit_status_type_t Cause of process termination. .. index:: pair: typedef; tapi_cfg_ps_exit_status_t .. _doxid-group__tapi__conf__process_1ga12f53d9c0b9b9fedc2c2dbbbddbf84b1: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_cfg_ps_exit_status_t` tapi_cfg_ps_exit_status_t Structure that represents status of a terminated process. Global Functions ---------------- .. index:: pair: function; tapi_cfg_ps_add .. _doxid-group__tapi__conf__process_1gac83c93a8478749146d2956452e74f4d2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_add(const char* ta, const char* ps_name, const char* exe, bool start) Add process. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process name. * - exe - Executable to run. * - start - Start it just after addition .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_del .. _doxid-group__tapi__conf__process_1ga6c1aa61bb30a1d189bd5b8337e918645: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_del(const char* ta, const char* ps_name) Delete process. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process name. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_start .. _doxid-group__tapi__conf__process_1ga0e633c6e9f363e9dbe3ecd12d1b4de1b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_start(const char* ta, const char* ps_name) Start process. For autorestart processes this function should be called only once. The following process executions will be done by the autorestart subsystem. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process name. .. rubric:: Returns: Status code .. rubric:: See also: :ref:`tapi_cfg_ps_set_autorestart ` .. index:: pair: function; tapi_cfg_ps_stop .. _doxid-group__tapi__conf__process_1ga6dbef0da0b7e3b14a99a382b9fe6ec20: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_stop(const char* ta, const char* ps_name) Stop process. For autorestart processes this function will stop the process and prevent the autorestart subsystem from starting the process over until :ref:`tapi_cfg_ps_start() ` is called. Successfull call of this function guarantees that :ref:`tapi_cfg_ps_get_status() ` will return ``false``, thus the process parameters are allowed to be changed (using :ref:`tapi_cfg_ps_add_arg() `, etc.). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process name. .. rubric:: Returns: Status code .. rubric:: See also: :ref:`tapi_cfg_ps_set_autorestart ` .. index:: pair: function; tapi_cfg_ps_get_status .. _doxid-group__tapi__conf__process_1ga175e361cd779886169bac73f40e30dbe: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_get_status(const char* ta, const char* ps_name, bool* status) Get current process status. If ``status`` is ``false``, the process parameters are allowed to be changed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process name. * - status - Process current status. For autorestart processes ``true`` means that the autorestart subsystem is working with the process and it will be restarted when needed; ``false`` means that the process is most likely not running and will not be started by the autorestart subsystem. For other processes ``true`` means that the process is running, ``false`` that it is not. .. rubric:: Returns: Status code .. rubric:: See also: :ref:`tapi_cfg_ps_set_autorestart ` .. index:: pair: function; tapi_cfg_ps_add_arg .. _doxid-group__tapi__conf__process_1ga9f1148239f90ca99d7fa2a037bddfab2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_add_arg(const char* ta, const char* ps_name, unsigned int order, const char* arg) Add process argument. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - order - Relative order. * - arg - Argument itself. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_add_env .. _doxid-group__tapi__conf__process_1ga9ceb3c11818e590791d58e6ab45bab32: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_add_env(const char* ta, const char* ps_name, const char* env_name, const char* value) Add environment variable. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - env_name - Variable name. * - value - Variable value. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_add_opt .. _doxid-group__tapi__conf__process_1ga167b01c89dd7d6b849b21cb37cc3a326: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_add_opt(const char* ta, const char* ps_name, const char* opt_name, const char* value) Add option. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - opt_name - Option name. * - value - Option value. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_set_long_opt_sep .. _doxid-group__tapi__conf__process_1ga7e31e65b6e1aa116da4775d34f4697cc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_set_long_opt_sep(const char* ta, const char* ps_name, const char* value) Set long option value separator. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - value - Value to set. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_set_autorestart .. _doxid-group__tapi__conf__process_1ga5a5a536a5e45cb99f4353e2a3e5da135: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_set_autorestart(const char* ta, const char* ps_name, unsigned int value) Set autorestart timeout. The value represents a frequency with which the autorestart subsystem will check whether the process stopped running (regardless of the reason) and restart it if it did. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - value - Autorestart timeout in seconds or ``0`` to disable autorestart for the process. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_get_autorestart .. _doxid-group__tapi__conf__process_1ga6453fe420f5e959d316673650ed80ced: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_get_autorestart(const char* ta, const char* ps_name, unsigned int* value) Get autorestart timeout. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - value - Autorestart timeout in seconds. If ``0`` the autorestart is disabled. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_set_workdir .. _doxid-group__tapi__conf__process_1ga36e0b0835631f8a53e88bbef1e22dbd9: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_set_workdir(const char* ta, const char* ps_name, const char* workdir) Set working directory. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent name. * - ps_name - Process. * - workdir - New process working directory. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_ps_get_workdir .. _doxid-group__tapi__conf__process_1ga48cb994fc27678d165a8d86909a08dc3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_get_workdir(const char* ta, const char* ps_name, char** workdir) Get working directory. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent name. * - ps_name - Process. * - workdir - Process current working directory. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_ps_kill .. _doxid-group__tapi__conf__process_1ga80a89902593bb1283a657838e2edea0d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_kill(const char* ta, const char* ps_name, int signo) Send a signal to the process. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - signo - Number of signal to send. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_killpg .. _doxid-group__tapi__conf__process_1ga1bf04c35bbdf246c2f927507effe99cf: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_killpg(const char* ta, const char* ps_name, int signo) Send a signal to the process's porcess group. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - signo - Number of signal to send. .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_ps_wait .. _doxid-group__tapi__conf__process_1gacf460cb6cd553bd194c9aae0a42fbd9a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_ps_wait(const char* ta, const char* ps_name, int timeout_ms, :ref:`tapi_cfg_ps_exit_status_t`* exit_status) Wait for a process completion (or check its status if ``timeout_ms`` is zero). Parameters of the process are allowed to be changed after successful call of this function. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - ps_name - Process. * - timeout_ms - Time to wait for the process. ``0`` means to check current status and exit, negative value means that the call of the function blocks until the process changes its status. * - exit_status - Process exit status location, may be ``NULL``. * - 0 - The process completed running or was never started * - TE_EINPROGRESS - The process is still running. .. rubric:: Returns: Status code