support/capture_subprocess.h

   1 /* Capture output from a subprocess.
   2    Copyright (C) 2017-2024 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 and ENVP environments by using posix_spawn
  39    and capture standard output, standard error, and the exit status.  If
  40    ENVP is NULL the current environment variable is used.  The out.buffer and
  41    err.buffer are handle by support_capture_subprocess.  */
  42 struct support_capture_subprocess support_capture_subprogram
  43   (const char *file, char *const argv[], char *const envp[]);
  44
  45 /* Copy the running program into a setgid binary and run it with CHILD_ID
  46    argument.  If execution is successful, return the exit status of the child
  47    program, otherwise return a non-zero failure exit code.  */
  48 int support_capture_subprogram_self_sgid
  49   (char *child_id);
  50
  51 /* Deallocate the subprocess data captured by
  52    support_capture_subprocess.  */
  53 void support_capture_subprocess_free (struct support_capture_subprocess *);
  54
  55 enum support_capture_allow
  56 {
  57   /* No output is allowed.  */
  58   sc_allow_none = 0x01,
  59   /* Output to stdout is permitted.  */
  60   sc_allow_stdout = 0x02,
  61   /* Output to standard error is permitted.  */
  62   sc_allow_stderr = 0x04,
  63 };
  64
  65 /* Check that the subprocess exited and that only the allowed outputs
  66    happened.  If STATUS_OR_SIGNAL is nonnegative, it is the expected
  67    (decoded) exit status of the process, as returned by WEXITSTATUS.
  68    If STATUS_OR_SIGNAL is negative, -STATUS_OR_SIGNAL is the expected
  69    termination signal, as returned by WTERMSIG.  ALLOWED is a
  70    combination of support_capture_allow flags.  Report errors under
  71    the CONTEXT message.  */
  72 void support_capture_subprocess_check (struct support_capture_subprocess *,
  73                                        const char *context,
  74                                        int status_or_signal, int allowed)
  75   __attribute__ ((nonnull (1, 2)));
  76
  77 #endif /* SUPPORT_CAPTURE_SUBPROCESS_H */