1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_SPAWN_H 3 #define _GLIBMM_SPAWN_H 4 5 6 /* Copyright (C) 2002 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmmconfig.h> 24 #include <glibmm/arrayhandle.h> 25 #include <glibmm/error.h> 26 #include <sigc++/sigc++.h> 27 #include <string> 28 29 namespace Glib 30 { 31 32 using Pid = GPid; 33 34 /** @addtogroup glibmmEnums glibmm Enums and Flags */ 35 36 /** 37 * @var SpawnFlags SPAWN_DEFAULT 38 * No flags, default behaviour. 39 * 40 * @var SpawnFlags SPAWN_LEAVE_DESCRIPTORS_OPEN 41 * The parent's open file descriptors will 42 * be inherited by the child; otherwise all descriptors except stdin, 43 * stdout and stderr will be closed before calling exec() in the child. 44 * 45 * @var SpawnFlags SPAWN_DO_NOT_REAP_CHILD 46 * The child will not be automatically reaped; 47 * you must use g_child_watch_add() yourself (or call waitpid() or handle 48 * `SIGCHLD` yourself), or the child will become a zombie. 49 * 50 * @var SpawnFlags SPAWN_SEARCH_PATH 51 * `argv[0]` need not be an absolute path, it will be 52 * looked for in the user's `PATH`. 53 * 54 * @var SpawnFlags SPAWN_STDOUT_TO_DEV_NULL 55 * The child's standard output will be discarded, 56 * instead of going to the same location as the parent's standard output. 57 * 58 * @var SpawnFlags SPAWN_STDERR_TO_DEV_NULL 59 * The child's standard error will be discarded. 60 * 61 * @var SpawnFlags SPAWN_CHILD_INHERITS_STDIN 62 * The child will inherit the parent's standard 63 * input (by default, the child's standard input is attached to `/dev/null`). 64 * 65 * @var SpawnFlags SPAWN_FILE_AND_ARGV_ZERO 66 * The first element of `argv` is the file to 67 * execute, while the remaining elements are the actual argument vector 68 * to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` 69 * as the file to execute, and passes all of `argv` to the child. 70 * 71 * @var SpawnFlags SPAWN_SEARCH_PATH_FROM_ENVP 72 * If `argv[0]` is not an abolute path, 73 * it will be looked for in the `PATH` from the passed child environment. 74 * @newin{2,34} 75 * 76 * @var SpawnFlags SPAWN_CLOEXEC_PIPES 77 * Create all pipes with the `O_CLOEXEC` flag set. 78 * @newin{2,40} 79 * 80 * @enum SpawnFlags 81 * 82 * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). 83 * 84 * @ingroup glibmmEnums 85 * @par Bitwise operators: 86 * <tt>%SpawnFlags operator|(SpawnFlags, SpawnFlags)</tt><br> 87 * <tt>%SpawnFlags operator&(SpawnFlags, SpawnFlags)</tt><br> 88 * <tt>%SpawnFlags operator^(SpawnFlags, SpawnFlags)</tt><br> 89 * <tt>%SpawnFlags operator~(SpawnFlags)</tt><br> 90 * <tt>%SpawnFlags& operator|=(SpawnFlags&, SpawnFlags)</tt><br> 91 * <tt>%SpawnFlags& operator&=(SpawnFlags&, SpawnFlags)</tt><br> 92 * <tt>%SpawnFlags& operator^=(SpawnFlags&, SpawnFlags)</tt><br> 93 */ 94 enum SpawnFlags 95 { 96 SPAWN_DEFAULT = 0x0, 97 SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, 98 SPAWN_DO_NOT_REAP_CHILD = 1 << 1, 99 SPAWN_SEARCH_PATH = 1 << 2, 100 SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, 101 SPAWN_STDERR_TO_DEV_NULL = 1 << 4, 102 SPAWN_CHILD_INHERITS_STDIN = 1 << 5, 103 SPAWN_FILE_AND_ARGV_ZERO = 1 << 6, 104 SPAWN_SEARCH_PATH_FROM_ENVP = 1 << 7, 105 SPAWN_CLOEXEC_PIPES = 1 << 8 106 }; 107 108 /** @ingroup glibmmEnums */ 109 inline SpawnFlags operator|(SpawnFlags lhs, SpawnFlags rhs) 110 { return static_cast<SpawnFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); } 111 112 /** @ingroup glibmmEnums */ 113 inline SpawnFlags operator&(SpawnFlags lhs, SpawnFlags rhs) 114 { return static_cast<SpawnFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); } 115 116 /** @ingroup glibmmEnums */ 117 inline SpawnFlags operator^(SpawnFlags lhs, SpawnFlags rhs) 118 { return static_cast<SpawnFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); } 119 120 /** @ingroup glibmmEnums */ 121 inline SpawnFlags operator~(SpawnFlags flags) 122 { return static_cast<SpawnFlags>(~static_cast<unsigned>(flags)); } 123 124 /** @ingroup glibmmEnums */ 125 inline SpawnFlags& operator|=(SpawnFlags& lhs, SpawnFlags rhs) 126 { return (lhs = static_cast<SpawnFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); } 127 128 /** @ingroup glibmmEnums */ 129 inline SpawnFlags& operator&=(SpawnFlags& lhs, SpawnFlags rhs) 130 { return (lhs = static_cast<SpawnFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); } 131 132 /** @ingroup glibmmEnums */ 133 inline SpawnFlags& operator^=(SpawnFlags& lhs, SpawnFlags rhs) 134 { return (lhs = static_cast<SpawnFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); } 135 136 137 /** @defgroup Spawn Spawning Processes 138 * Process launching with fork()/exec(). 139 * @{ 140 */ 141 142 /** %Exception class for errors occuring when spawning processes. 143 */ 144 class GLIBMM_API SpawnError : public Glib::Error 145 { 146 public: 147 /** @var Code FORK 148 * Fork failed due to lack of memory. 149 * 150 * @var Code READ 151 * Read or select on pipes failed. 152 * 153 * @var Code CHDIR 154 * Changing to working directory failed. 155 * 156 * @var Code ACCES 157 * Execv() returned `EACCES`. 158 * 159 * @var Code PERM 160 * Execv() returned `EPERM`. 161 * 162 * @var Code TOO_BIG 163 * Execv() returned `E2BIG`. 164 * 165 * @var Code TOOBIG 166 * Deprecated alias for SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32). 167 * 168 * @var Code NOEXEC 169 * Execv() returned `ENOEXEC`. 170 * 171 * @var Code NAMETOOLONG 172 * Execv() returned `ENAMETOOLONG`. 173 * 174 * @var Code NOENT 175 * Execv() returned `ENOENT`. 176 * 177 * @var Code NOMEM 178 * Execv() returned `ENOMEM`. 179 * 180 * @var Code NOTDIR 181 * Execv() returned `ENOTDIR`. 182 * 183 * @var Code LOOP 184 * Execv() returned `ELOOP`. 185 * 186 * @var Code TXTBUSY 187 * Execv() returned `ETXTBUSY`. 188 * 189 * @var Code IO 190 * Execv() returned `EIO`. 191 * 192 * @var Code NFILE 193 * Execv() returned `ENFILE`. 194 * 195 * @var Code MFILE 196 * Execv() returned `EMFILE`. 197 * 198 * @var Code INVAL 199 * Execv() returned `EINVAL`. 200 * 201 * @var Code ISDIR 202 * Execv() returned `EISDIR`. 203 * 204 * @var Code LIBBAD 205 * Execv() returned `ELIBBAD`. 206 * 207 * @var Code FAILED 208 * Some other fatal failure, 209 * `error->message` should explain. 210 * 211 * @enum Code 212 * 213 * %Error codes returned by spawning processes. 214 */ 215 enum Code 216 { 217 FORK, 218 READ, 219 CHDIR, 220 ACCES, 221 PERM, 222 TOO_BIG, 223 TOOBIG = TOO_BIG, 224 NOEXEC, 225 NAMETOOLONG, 226 NOENT, 227 NOMEM, 228 NOTDIR, 229 LOOP, 230 TXTBUSY, 231 IO, 232 NFILE, 233 MFILE, 234 INVAL, 235 ISDIR, 236 LIBBAD, 237 FAILED 238 }; 239 240 SpawnError(Code error_code, const Glib::ustring& error_message); 241 explicit SpawnError(GError* gobject); 242 Code code() const; 243 244 #ifndef DOXYGEN_SHOULD_SKIP_THIS 245 private: 246 247 static void throw_func(GError* gobject); 248 249 friend GLIBMM_API void wrap_init(); // uses throw_func() 250 251 #endif //DOXYGEN_SHOULD_SKIP_THIS 252 }; 253 254 255 /** For instance,<br> 256 * void on_child_setup(); 257 */ 258 using SlotSpawnChildSetup = sigc::slot<void>; 259 260 /** Executes a child program asynchronously (your program will not 261 * block waiting for the child to exit). The child program is 262 * specified by the only argument that must be provided, @a argv. 263 * The first string in @a argv is of 264 * course the name of the program to execute. By default, the name of 265 * the program must be a full path; the PATH shell variable 266 * will only be searched if you pass the SPAWN_SEARCH_PATH flag. 267 * 268 * On Windows, note that all the string or string vector arguments to 269 * this function and the other spawn*() functions are in UTF-8, the 270 * GLib file name encoding. Unicode characters that are not part of 271 * the system codepage passed in these arguments will be correctly 272 * available in the spawned program only if it uses wide character API 273 * to retrieve its command line. For C programs built with Microsoft's 274 * tools it is enough to make the program have a wmain() instead of 275 * main(). wmain() has a wide character argument vector as parameter. 276 * 277 * At least currently, mingw doesn't support wmain(), so if you use 278 * mingw to develop the spawned program, it will have to call the 279 * undocumented function __wgetmainargs() to get the wide character 280 * argument vector and environment. See gspawn-win32-helper.c in the 281 * GLib sources or init.c in the mingw runtime sources for a prototype 282 * for that function. Alternatively, you can retrieve the Win32 system 283 * level wide character command line passed to the spawned program 284 * using the GetCommandLineW() function. 285 * 286 * On Windows the low-level child process creation API 287 * CreateProcess() doesn't use argument vectors, 288 * but a command line. The C runtime library's 289 * spawn*() family of functions (which 290 * spawn_async_with_pipes() eventually calls) paste the argument 291 * vector elements together into a command line, and the C runtime startup code 292 * does a corresponding reconstruction of an argument vector from the 293 * command line, to be passed to main(). Complications arise when you have 294 * argument vector elements that contain spaces of double quotes. The 295 * spawn*() functions don't do any quoting or 296 * escaping, but on the other hand the startup code does do unquoting 297 * and unescaping in order to enable receiving arguments with embedded 298 * spaces or double quotes. To work around this asymmetry, 299 * spawn_async_with_pipes() will do quoting and escaping on argument 300 * vector elements that need it before calling the C runtime 301 * spawn() function. 302 * 303 * @a envp is a lists of strings, where each string 304 * has the form KEY=VALUE. This will become 305 * the child's environment. 306 * 307 * @a flags should be the bitwise OR of any flags you want to affect the 308 * function's behaviour. The SPAWN_DO_NOT_REAP_CHILD flags means that 309 * the child will not automatically be reaped; you must use a 310 * ChildWatch source to be notified about the death of the child 311 * process. Eventually you must call spawn_close_pid() on the 312 * @a child_pid, in order to free resources which may be associated 313 * with the child process. (On Unix, using a ChildWatch source is 314 * equivalent to calling waitpid() or handling the SIGCHLD signal 315 * manually. On Windows, calling spawn_close_pid() is equivalent 316 * to calling CloseHandle() on the process handle returned in 317 * @a child_pid). 318 * 319 * PAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file 320 * descriptors will be inherited by the child; otherwise all 321 * descriptors except stdin/stdout/stderr will be closed before 322 * calling exec() in the child. SPAWN_SEARCH_PATH 323 * means that argv[0] need not be an absolute path, it 324 * will be looked for in the user's PATH. 325 * SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will 326 * be discarded, instead of going to the same location as the parent's 327 * standard output. If you use this flag, @a standard_output must be nullptr. 328 * SPAWN_STDERR_TO_DEV_NULL means that the child's standard error 329 * will be discarded, instead of going to the same location as the parent's 330 * standard error. If you use this flag, @a standard_error must be nullptr. 331 * SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's 332 * standard input (by default, the child's standard input is attached to 333 * /dev/null). If you use this flag, @a standard_input must be nullptr. 334 * G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @a argv is 335 * the file to execute, while the remaining elements are the 336 * actual argument vector to pass to the file. Normally 337 * spawn_async_with_pipes() uses argv[0] as the file to execute, and 338 * passes all of @a argv to the child. 339 * 340 * @a child_setup is a callback slot. On POSIX 341 * platforms, the function is called in the child after GLib has 342 * performed all the setup it plans to perform (including creating 343 * pipes, closing file descriptors, etc.) but before calling 344 * exec(). That is, @a child_setup is called just 345 * before calling exec() in the child. Obviously 346 * actions taken in this function will only affect the child, not the 347 * parent. On Windows, there is no separate fork() and exec() 348 * functionality. Child processes are created and run with 349 * a single API call, CreateProcess(). @a child_setup is 350 * called in the parent process just before creating the child 351 * process. You should carefully consider what you do in @a child_setup 352 * if you intend your software to be portable to Windows. 353 * 354 * If non-nullptr, @a child_pid will on Unix be filled with the child's 355 * process ID. You can use the process ID to send signals to the 356 * child, or to use child_watch_add() (or waitpid()) if you specified the 357 * SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @a child_pid will be 358 * filled with a handle to the child process only if you specified the 359 * SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child 360 * process using the Win32 API, for example wait for its termination 361 * with the WaitFor*() functions, or examine its 362 * exit code with GetExitCodeProcess(). You should close the handle 363 * with CloseHandle() or spawn_close_pid() when you no longer need it. 364 * 365 * If non-nullptr, the @a standard_input, @a standard_output, @a standard_error 366 * locations will be filled with file descriptors for writing to the child's 367 * standard input or reading from its standard output or standard error. 368 * The caller of spawn_async_with_pipes() must close these file descriptors 369 * when they are no longer in use. If these parameters are nullptr, the corresponding 370 * pipe won't be created. 371 * 372 * If @a standard_input is nullptr, the child's standard input is attached to 373 * /dev/null unless SPAWN_CHILD_INHERITS_STDIN is set. 374 * 375 * If @a standard_error is nullptr, the child's standard error goes to the same 376 * location as the parent's standard error unless SPAWN_STDERR_TO_DEV_NULL 377 * is set. 378 * 379 * If @a standard_output is nullptr, the child's standard output goes to the same 380 * location as the parent's standard output unless SPAWN_STDOUT_TO_DEV_NULL 381 * is set. 382 * 383 * If @a child_pid is not nullptr and an error does not occur then the returned 384 * pid must be closed using spawn_close_pid(). 385 * 386 * @note 387 * If you are writing a gtkmm application, and the program you 388 * are spawning is a graphical application, too, then you may 389 * want to use spawn_on_screen_with_pipes() instead to ensure that 390 * the spawned program opens its windows on the right screen. 391 * 392 * @param working_directory Child's current working directory, or an empty string to inherit the parent's, in the GLib file name encoding. 393 * @param argv Child's argument vector. 394 * @param envp Child's environment. 395 * @param flags Flags from SpawnFlags 396 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 397 * @param child_pid Return location for child process ID, or nullptr. 398 * @param standard_input Return location for file descriptor to write to child's stdin, or nullptr. 399 * @param standard_output Return location for file descriptor to read child's stdout, or nullptr. 400 * @param standard_error Return location for file descriptor to read child's stderr, or nullptr. 401 * 402 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 403 * executable in argv[0] is not found). Typically 404 * the message field of returned errors should be displayed 405 * to users. If an error occurs, @a child_pid, @a standard_input, @a standard_output, 406 * and @a standard_error will not be filled with valid values. 407 */ 408 GLIBMM_API 409 void spawn_async_with_pipes(const std::string& working_directory, 410 const Glib::ArrayHandle<std::string>& argv, 411 const Glib::ArrayHandle<std::string>& envp, 412 SpawnFlags flags = SPAWN_DEFAULT, 413 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 414 Pid* child_pid = nullptr, 415 int* standard_input = nullptr, 416 int* standard_output = nullptr, 417 int* standard_error = nullptr); 418 419 /** Like the main spawn_async_with_pipes() method, but inheriting the parent's environment. 420 * 421 * @param working_directory Child's current working directory, or an empty string to inherit the parent's, in the GLib file name encoding. 422 * @param argv Child's argument vector. 423 * @param flags Flags from SpawnFlags 424 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 425 * @param child_pid Return location for child process ID, or nullptr. 426 * @param standard_input Return location for file descriptor to write to child's stdin, or nullptr. 427 * @param standard_output Return location for file descriptor to read child's stdout, or nullptr. 428 * @param standard_error Return location for file descriptor to read child's stderr, or nullptr. 429 * 430 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 431 * executable in argv[0] is not found). Typically 432 * the message field of returned errors should be displayed 433 * to users. If an error occurs, @a child_pid, @a standard_input, @a standard_output, 434 * and @a standard_error will not be filled with valid values. 435 */ 436 GLIBMM_API 437 void spawn_async_with_pipes(const std::string& working_directory, 438 const Glib::ArrayHandle<std::string>& argv, 439 SpawnFlags flags = SPAWN_DEFAULT, 440 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 441 Pid* child_pid = nullptr, 442 int* standard_input = nullptr, 443 int* standard_output = nullptr, 444 int* standard_error = nullptr); 445 446 /** See spawn_async_with_pipes() for a full description. This function 447 * simply calls the spawn_async_with_pipes() without any pipes. 448 * 449 * @note 450 * If you are writing a GTK+ application, and the program you 451 * are spawning is a graphical application, too, then you may 452 * want to use gdk_spawn_on_screen() instead to ensure that 453 * the spawned program opens its windows on the right screen. 454 * 455 * @param working_directory Child's current working directory, or an empty string to inherit parent's. 456 * @param argv Child's argument vector. 457 * @param envp Child's environment. 458 * @param flags Flags from SpawnFlags. 459 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 460 * @param child_pid Return location for child process ID, or nullptr 461 * 462 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 463 * executable in argv[0] is not found). Typically 464 * the message field of returned errors should be displayed 465 * to users. 466 */ 467 GLIBMM_API 468 void spawn_async(const std::string& working_directory, 469 const Glib::ArrayHandle<std::string>& argv, 470 const Glib::ArrayHandle<std::string>& envp, 471 SpawnFlags flags = SPAWN_DEFAULT, 472 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 473 Pid* child_pid = nullptr); 474 475 /** Like the main spawn_async() method, but inheriting the parent's environment. 476 * 477 * @param working_directory Child's current working directory, or an empty string to inherit parent's. 478 * @param argv Child's argument vector. 479 * @param flags Flags from SpawnFlags. 480 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 481 * @param child_pid Return location for child process ID, or nullptr 482 * 483 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 484 * executable in argv[0] is not found). Typically 485 * the message field of returned errors should be displayed 486 * to users. 487 */ 488 GLIBMM_API 489 void spawn_async(const std::string& working_directory, 490 const Glib::ArrayHandle<std::string>& argv, 491 SpawnFlags flags = SPAWN_DEFAULT, 492 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 493 Pid* child_pid = nullptr); 494 495 /** Executes a child synchronously (waits for the child to exit before returning). 496 * All output from the child is stored in @a standard_output and @a standard_error, 497 * if those parameters are non-nullptr. Note that you must set the 498 * SPAWN_STDOUT_TO_DEV_NULL and SPAWN_STDERR_TO_DEV_NULL flags when 499 * passing nullptr for @a standard_output and @a standard_error. 500 * If @a exit_status is non-nullptr, the exit status of the child is stored 501 * there as it would be returned by waitpid(); standard UNIX macros such 502 * as WIFEXITED() and WEXITSTATUS() must be used to evaluate the exit status. 503 * Note that this function calls waitpid() even if @a exit_status is nullptr, and 504 * does not accept the SPAWN_DO_NOT_REAP_CHILD flag. 505 * If an error occurs, no data is returned in @a standard_output, 506 * @a standard_error, or @a exit_status. 507 * 508 * This function calls spawn_async_with_pipes() internally; see that 509 * function for full details on the other parameters and details on 510 * how these functions work on Windows. 511 * 512 * @param working_directory Child's current working directory, or an empty string to inherit the parent's, in the GLib file name encoding. 513 * @param argv Child's argument vector. 514 * @param envp Child's environment. 515 * @param flags Flags from SpawnFlags 516 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 517 * @param standard_output Return location for file descriptor to read child's stdout, or nullptr. 518 * @param standard_error Return location for file descriptor to read child's stderr, or nullptr. 519 * @param exit_status Return location for child exit status, as returned by waitpid(), or nullptr 520 * 521 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 522 * executable in argv[0] is not found). Typically 523 * the message field of returned errors should be displayed 524 * to users. If an error occurs, @a child_pid, @a standard_input, @a standard_output, 525 * and @a standard_error will not be filled with valid values. 526 */ 527 GLIBMM_API 528 void spawn_sync(const std::string& working_directory, 529 const Glib::ArrayHandle<std::string>& argv, 530 const Glib::ArrayHandle<std::string>& envp, 531 SpawnFlags flags = SPAWN_DEFAULT, 532 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 533 std::string* standard_output = nullptr, 534 std::string* standard_error = nullptr, 535 int* exit_status = nullptr); 536 537 /** Like the main spawn_sync() method, but inheriting the parent's environment. 538 * 539 * @param working_directory Child's current working directory, or an empty string to inherit the parent's, in the GLib file name encoding. 540 * @param argv Child's argument vector. 541 * @param flags Flags from SpawnFlags 542 * @param child_setup Slot to run in the child just before exec(), or an empty slot. 543 * @param standard_output Return location for file descriptor to read child's stdout, or nullptr. 544 * @param standard_error Return location for file descriptor to read child's stderr, or nullptr. 545 * @param exit_status Return location for child exit status, as returned by waitpid(), or nullptr 546 * 547 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 548 * executable in argv[0] is not found). Typically 549 * the message field of returned errors should be displayed 550 * to users. If an error occurs, @a child_pid, @a standard_input, @a standard_output, 551 * and @a standard_error will not be filled with valid values. 552 */ 553 GLIBMM_API 554 void spawn_sync(const std::string& working_directory, 555 const Glib::ArrayHandle<std::string>& argv, 556 SpawnFlags flags = SPAWN_DEFAULT, 557 const SlotSpawnChildSetup& child_setup = SlotSpawnChildSetup(), 558 std::string* standard_output = nullptr, 559 std::string* standard_error = nullptr, 560 int* exit_status = nullptr); 561 562 /** A simple version of spawn_async() that parses a command line with 563 * shell_parse_argv() and passes it to spawn_async(). It runs a 564 * command line in the background. Unlike spawn_async(), the 565 * SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note 566 * that SPAWN_SEARCH_PATH can have security implications, so 567 * consider using spawn_async() directly if appropriate. 568 * 569 * The same concerns on Windows apply as for spawn_command_line_sync(). 570 * 571 * @param command_line A command line. 572 * 573 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 574 * executable in argv[0] is not found). Typically 575 * the message field of returned errors should be displayed 576 * to users. 577 * @throws ShellError If the command line could not be parsed. 578 */ 579 GLIBMM_API 580 void spawn_command_line_async(const std::string& command_line); 581 582 /** A simple version of spawn_sync() with little-used parameters 583 * removed, taking a command line instead of an argument vector. See 584 * spawn_sync() for full details. @a command_line will be parsed by 585 * shell_parse_argv(). Unlike spawn_sync(), the SPAWN_SEARCH_PATH flag 586 * is enabled. Note that SPAWN_SEARCH_PATH can have security 587 * implications, so consider using spawn_sync() directly if 588 * appropriate. 589 * 590 * If @a exit_status is non-nullptr, the exit status of the child is stored there as 591 * it would be returned by waitpid(); standard UNIX macros such as WIFEXITED() 592 * and WEXITSTATUS() must be used to evaluate the exit status. 593 * 594 * On Windows, please note the implications of shell_parse_argv() 595 * parsing @a command_line. Parsing is done according to Unix shell rules, not 596 * Windows command interpreter rules. 597 * Space is a separator, and backslashes are 598 * special. Thus you cannot simply pass a @a command_line containing 599 * canonical Windows paths, like "c:\\program files\\app\\app.exe", as 600 * the backslashes will be eaten, and the space will act as a 601 * separator. You need to enclose such paths with single quotes, like 602 * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". 603 * 604 * @param command_line A command line. 605 * @param standard_output Return location for child output. 606 * @param standard_error Return location for child errors. 607 * @param exit_status Return location for child exit status, as returned by waitpid(). 608 * 609 * @throws SpawnError Errors are reported even if they occur in the child (for example if the 610 * executable in argv[0] is not found). Typically 611 * the message field of returned errors should be displayed 612 * to users. 613 * @throws ShellError If the command line could not be parsed. 614 */ 615 GLIBMM_API 616 void spawn_command_line_sync(const std::string& command_line, 617 std::string* standard_output = nullptr, 618 std::string* standard_error = nullptr, 619 int* exit_status = nullptr); 620 621 /** On some platforms, notably WIN32, the Pid type represents a resource 622 * which must be closed to prevent resource leaking. close_pid() 623 * is provided for this purpose. It should be used on all platforms, even 624 * though it doesn't do anything under UNIX. 625 * 626 * @param pid The process identifier to close. 627 */ 628 GLIBMM_API 629 void spawn_close_pid(Pid pid); 630 631 /** @} group Spawn */ 632 633 } // namespace Glib 634 635 636 #endif /* _GLIBMM_SPAWN_H */ 637 638