1  /* Capture output from a subprocess.
       2     Copyright (C) 2017-2023 Free Software Foundation, Inc.
       3     This file is part of the GNU C Library.
       4  
       5     The GNU C Library is free software; you can redistribute it and/or
       6     modify it under the terms of the GNU Lesser General Public
       7     License as published by the Free Software Foundation; either
       8     version 2.1 of the License, or (at your option) any later version.
       9  
      10     The GNU C Library is distributed in the hope that it will be useful,
      11     but WITHOUT ANY WARRANTY; without even the implied warranty of
      12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      13     Lesser General Public License for more details.
      14  
      15     You should have received a copy of the GNU Lesser General Public
      16     License along with the GNU C Library; if not, see
      17     <https://www.gnu.org/licenses/>.  */
      18  
      19  #ifndef SUPPORT_CAPTURE_SUBPROCESS_H
      20  #define SUPPORT_CAPTURE_SUBPROCESS_H
      21  
      22  #include <support/xmemstream.h>
      23  
      24  struct support_capture_subprocess
      25  {
      26    struct xmemstream out;
      27    struct xmemstream err;
      28    int status;
      29  };
      30  
      31  /* Invoke CALLBACK (CLOSURE) in a subprocess and capture standard
      32     output, standard error, and the exit status.  The out.buffer and
      33     err.buffer members in the result are null-terminated strings which
      34     can be examined by the caller (out.out and err.out are NULL).  */
      35  struct support_capture_subprocess support_capture_subprocess
      36    (void (*callback) (void *), void *closure);
      37  
      38  /* Issue FILE with ARGV arguments by using posix_spawn and capture standard
      39     output, standard error, and the exit status.  The out.buffer and err.buffer
      40     are handle as support_capture_subprocess.  */
      41  struct support_capture_subprocess support_capture_subprogram
      42    (const char *file, char *const argv[]);
      43  
      44  /* Copy the running program into a setgid binary and run it with CHILD_ID
      45     argument.  If execution is successful, return the exit status of the child
      46     program, otherwise return a non-zero failure exit code.  */
      47  int support_capture_subprogram_self_sgid
      48    (char *child_id);
      49  
      50  /* Deallocate the subprocess data captured by
      51     support_capture_subprocess.  */
      52  void support_capture_subprocess_free (struct support_capture_subprocess *);
      53  
      54  enum support_capture_allow
      55  {
      56    /* No output is allowed.  */
      57    sc_allow_none = 0x01,
      58    /* Output to stdout is permitted.  */
      59    sc_allow_stdout = 0x02,
      60    /* Output to standard error is permitted.  */
      61    sc_allow_stderr = 0x04,
      62  };
      63  
      64  /* Check that the subprocess exited and that only the allowed outputs
      65     happened.  If STATUS_OR_SIGNAL is nonnegative, it is the expected
      66     (decoded) exit status of the process, as returned by WEXITSTATUS.
      67     If STATUS_OR_SIGNAL is negative, -STATUS_OR_SIGNAL is the expected
      68     termination signal, as returned by WTERMSIG.  ALLOWED is a
      69     combination of support_capture_allow flags.  Report errors under
      70     the CONTEXT message.  */
      71  void support_capture_subprocess_check (struct support_capture_subprocess *,
      72                                         const char *context,
      73                                         int status_or_signal, int allowed)
      74    __attribute__ ((nonnull (1, 2)));
      75  
      76  #endif /* SUPPORT_CAPTURE_SUBPROCESS_H */