include/vlc_spawn.h

   1 /*****************************************************************************
   2  * vlc_spawn.h: Child process helpers
   3  *****************************************************************************
   4  * Copyright © 2020 Rémi Denis-Courmont
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation; either version 2.1 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  19  *****************************************************************************/
  20
  21 #ifndef VLC_SPAWN_H
  22 #define VLC_SPAWN_H 1
  23
  24 #include <sys/types.h>
  25
  26 /**
  27  * \defgroup spawn Process management
  28  * \ingroup os
  29  * @{
  30  */
  31
  32 /**
  33  * Spawn a child process (by file name).
  34  *
  35  * This function creates a child process. For all practical purposes, it is
  36  * identical to vlc_spawnp(), with one exception: vlc_spawn() does <b>not</b>
  37  * look for the executable file name in the OS-defined search path. Instead the
  38  * file name must be absolute.
  39  *
  40  * \param pid storage space for the child process identifier [OUT]
  41  * \param path executable file path [IN]
  42  * \param fdv file descriptor array [IN]
  43  * \param argv NULL-terminated array of command line arguments [IN]
  44  *
  45  * \return 0 on success or a standard error code on failure
  46  */
  47 VLC_API VLC_USED
  48 int vlc_spawn(pid_t *pid, const char *file, const int *fdv,
  49               const char *const *argv);
  50
  51 /**
  52  * Spawn a child process.
  53  *
  54  * This function creates a child process. The created process will run with the
  55  * same environment and privileges as the calling process.
  56  *
  57  * An array of file descriptors must be provided for the child process:
  58  * - fdv[0] is the standard input (or -1 for nul input),
  59  * - fdv[1] is the standard output (or -1 for nul output),
  60  * - fdv[2] is the standard error (or -1 to ignore).
  61  * The array must have at least 4 elements and be terminated by -1.
  62  * Some platforms will ignore file descriptors other than the three standard
  63  * ones, so those should not be used in code intended to be portable.
  64  *
  65  * vlc_waitpid() must be called to collect outstanding system resources
  66  * after the child process terminates.
  67  *
  68  * \param pid storage space for the child process identifier [OUT]
  69  * \param path executable path [IN]
  70  * \param fdv file descriptor array [IN]
  71  * \param argv NULL-terminated array of command line arguments [IN]
  72  *
  73  * \return 0 on success or a standard error code on failure
  74  */
  75 VLC_API VLC_USED
  76 int vlc_spawnp(pid_t *pid, const char *path, const int *fdv,
  77               const char *const *argv);
  78
  79 /**
  80  * Waits for a child process.
  81  *
  82  * This function waits until a child process created by vlc_spawn() or
  83  * vlc_spawnp() has completed and releases any associated system resource.
  84  *
  85  * \param pid process identifier as returned by vlc_spawn() or vlc_spawnp()
  86  *
  87  * \return This function returns the process exit code.
  88  */
  89 VLC_API
  90 int vlc_waitpid(pid_t pid);
  91
  92 /** @} */
  93
  94 #endif