wsutil/ws_pipe.h

   1 /** @file
   2  *
   3  * Routines for handling pipes.
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __WS_PIPE_H__
  13 #define __WS_PIPE_H__
  14
  15 #include <stdbool.h>
  16
  17 // ws_symbol_export and WS_INVALID_PID
  18 #include "wsutil/processes.h"
  19
  20 #include <glib.h>
  21
  22 #ifdef _WIN32
  23 #include <windows.h>
  24 #include <io.h>
  25 #define ws_pipe_handle                  HANDLE
  26 #define ws_get_pipe_handle(pipe_fd)     ((HANDLE)_get_osfhandle(pipe_fd))
  27 #else
  28 #define ws_pipe_handle                  int
  29 #define ws_get_pipe_handle(pipe_fd)     (pipe_fd)
  30 #endif
  31
  32 typedef struct _ws_pipe_t {
  33     GPid pid;
  34     GIOChannel *stdin_io;
  35     GIOChannel *stdout_io;
  36     GIOChannel *stderr_io;
  37 } ws_pipe_t;
  38
  39 /**
  40  * @brief Run a process using g_spawn_sync on UNIX and Linux, and
  41  *        CreateProcess on Windows. Wait for it to finish.
  42  * @param [IN] working_directory Initial working directory.
  43  * @param [IN] command Command to run.
  44  * @param [IN] argc Number of arguments for the command, not including the command itself.
  45  * @param [IN] args Arguments for the command, not including the command itself.
  46  * The last element must be NULL.
  47  * @param [OUT] command_output If not NULL, receives a copy of the command output. Must be g_freed.
  48  * @return true on success or false on failure.
  49  */
  50 WS_DLL_PUBLIC bool ws_pipe_spawn_sync(const char * working_directory, const char * command, int argc, char ** args, char ** command_output);
  51
  52 /**
  53  * @brief Initialize a ws_pipe_t struct. Sets .pid to WS_INVALID_PID and all other members to 0 or NULL.
  54  * @param ws_pipe [IN] The pipe to initialize.
  55  */
  56 WS_DLL_PUBLIC void ws_pipe_init(ws_pipe_t *ws_pipe);
  57
  58 /**
  59  * @brief Checks whether a pipe is valid (for reading or writing).
  60  */
  61 static inline bool ws_pipe_valid(ws_pipe_t *ws_pipe)
  62 {
  63     return ws_pipe && ws_pipe->pid && ws_pipe->pid != WS_INVALID_PID;
  64 }
  65
  66 /**
  67  * @brief Start a process using g_spawn_sync on UNIX and Linux, and CreateProcess on Windows.
  68  * @param ws_pipe The process PID, stdio descriptors, etc.
  69  * @param args The command to run along with its arguments.
  70  * @return A valid PID on success, otherwise WS_INVALID_PID.
  71  */
  72 WS_DLL_PUBLIC GPid ws_pipe_spawn_async (ws_pipe_t * ws_pipe, GPtrArray * args );
  73
  74 #ifdef _WIN32
  75 /**
  76  * @brief Wait for a set of handles using WaitForMultipleObjects. Windows only.
  77  * @param pipe_handles An array of handles
  78  * @param num_pipe_handles The size of the array.
  79  * @param pid Child process PID.
  80  * @return true on success or false on failure.
  81  */
  82 WS_DLL_PUBLIC bool ws_pipe_wait_for_pipe(HANDLE * pipe_handles, int num_pipe_handles, HANDLE pid);
  83 #endif
  84
  85 /**
  86  * @brief Check to see if a file descriptor has data available.
  87  * @param pipe_fd File descriptor.
  88  * @return true if data is available or false otherwise.
  89  */
  90 WS_DLL_PUBLIC bool ws_pipe_data_available(int pipe_fd);
  91
  92 #endif /* __WS_PIPE_H__ */
  93
  94 /*
  95  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
  96  *
  97  * Local variables:
  98  * c-basic-offset: 4
  99  * tab-width: 8
 100  * indent-tabs-mode: nil
 101  * End:
 102  *
 103  * vi: set shiftwidth=4 tabstop=8 expandtab:
 104  * :indentSize=4:tabSize=8:noTabs=true:
 105  */