1 /* 2 * libcomcom.d 3 * Copyright (C) 2019 Victor Porton <porton@narod.ru> 4 * 5 * This program is free software: you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation, either version 3 of the License, or 8 * (at your option) any later version. 9 10 * This program 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 13 * GNU General Public License for more details. 14 15 * You should have received a copy of the GNU General Public License 16 * along with this program. If not, see <https://www.gnu.org/licenses/>. 17 */ 18 19 module libcomcom; 20 21 import core.sys.posix.signal; 22 23 extern extern(C): 24 25 /** 26 * Initialize the library. Call it before libcomcom_run_command(). 27 * Note that this erases the old SIGCHLD handler (if any). 28 * @return 0 on success and -1 on error (also sets `errno`). 29 * 30 * You should usually also initialize SIGTERM/SIGINT signal handlers. 31 */ 32 int libcomcom_init(); 33 34 /** 35 * Initialize the library. Call it before libcomcom_run_command(). 36 * The `old` signal action is stored internally (and restored by 37 * libcomcom_destroy() or libcomcom_terminate()). 38 * The old signal handler (the one obtained from `old` variable) is also 39 * called from our SIGCHLD handler. 40 * @return 0 on success and -1 on error (also sets `errno`). 41 * 42 * You should usually also initialize SIGTERM/SIGINT signal handlers. 43 */ 44 int libcomcom_init2(sigaction_t *old); 45 46 /** 47 * Initialize the library. Call it before libcomcom_run_command(). 48 * This function is like libcomcom_init2(), but the old SIGCHLD signal handler 49 * is obtained automatically (by sigaction() library function). 50 * 51 * WARNING: If before calling this SIGCHLD handler was set by signal() 52 * (not by sigaction()), then this function may not work (leads to undefined 53 * behavior) on some non-Unix systems. 54 * @return 0 on success and -1 on error (also sets `errno`). 55 * 56 * You should usually also initialize SIGTERM/SIGINT signal handlers. 57 */ 58 int libcomcom_init_stratum(); 59 60 /** 61 * Runs an OS command. 62 * @param input passed to command stdin 63 * @param input_len the length of the string passed to stdin 64 * @param output at this location is stored the command's stdout (call `free()` after use) 65 * @param output_len at this location is stored the length of command's stdout 66 * @param file the command to run (PATH used) 67 * @param argv arguments for the command to run 68 * @param envp environment for the command to run (pass `NULL` to duplicate our environment) 69 * @param timeout timeout in milliseconds, -1 means infinite timeout 70 * @return 0 on success and -1 on error (also sets `errno`). 71 */ 72 int libcomcom_run_command(const char *input, size_t input_len, 73 const char **output, size_t *output_len, 74 const char *file, const char** argv, 75 const char** envp, 76 int timeout); 77 78 /** 79 * Should be run for normal termination (not in SIGTERM/SIGINT handler) 80 * of our program. 81 * @return 0 on success and -1 on error (also sets `errno`). 82 */ 83 int libcomcom_destroy(); 84 85 /** 86 * Usually should be run in SIGTERM and SIGINT handlers. 87 * @return 0 on success and -1 on error (also sets `errno`). 88 */ 89 int libcomcom_terminate(); 90 91 /** 92 * Install SIGTERM and SIGINT handler which calls libcomcom_terminate(). 93 * @return 0 on success and -1 on error (also sets `errno`). 94 * 95 * You are recommended to use libcomcom_set_default_terminate2() 96 * instead. 97 */ 98 int libcomcom_set_default_terminate(); 99 100 /** 101 * Uninstall SIGTERM and SIGINT handler which calls libcomcom_terminate(). 102 * @return 0 on success and -1 on error (also sets `errno`). 103 * 104 * You are recommended to use libcomcom_reset_default_terminate2() 105 * instead. 106 */ 107 int libcomcom_reset_default_terminate(); 108 109 /** 110 * Install SIGTERM and SIGINT handler which calls libcomcom_terminate(). 111 * @return 0 on success and -1 on error (also sets `errno`). 112 * 113 * The installed signal handler also calls old signal handler automatically. 114 * 115 * WARNING: If before calling these handlers were set by signal() 116 * (not by sigaction()), then this function may not work (leads to undefined 117 * behavior) on some non-Unix systems. 118 */ 119 int libcomcom_set_default_terminate2(); 120 121 /** 122 * Resets to signal handlers which were before calling 123 * libcomcom_set_default_terminate2(). 124 * @return 0 on success and -1 on error (also sets `errno`). 125 */ 126 int libcomcom_reset_default_terminate2();