1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD 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 Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gio.SubprocessLauncher; 26 27 private import gio.Subprocess; 28 private import gio.c.functions; 29 public import gio.c.types; 30 private import glib.ConstructionException; 31 private import glib.ErrorG; 32 private import glib.GException; 33 private import glib.Str; 34 private import gobject.ObjectG; 35 public import gtkc.giotypes; 36 37 38 /** 39 * This class contains a set of options for launching child processes, 40 * such as where its standard input and output will be directed, the 41 * argument list, the environment, and more. 42 * 43 * While the #GSubprocess class has high level functions covering 44 * popular cases, use of this class allows access to more advanced 45 * options. It can also be used to launch multiple subprocesses with 46 * a similar configuration. 47 * 48 * Since: 2.40 49 */ 50 public class SubprocessLauncher : ObjectG 51 { 52 /** the main Gtk struct */ 53 protected GSubprocessLauncher* gSubprocessLauncher; 54 55 /** Get the main Gtk struct */ 56 public GSubprocessLauncher* getSubprocessLauncherStruct(bool transferOwnership = false) 57 { 58 if (transferOwnership) 59 ownedRef = false; 60 return gSubprocessLauncher; 61 } 62 63 /** the main Gtk struct as a void* */ 64 protected override void* getStruct() 65 { 66 return cast(void*)gSubprocessLauncher; 67 } 68 69 protected override void setStruct(GObject* obj) 70 { 71 gSubprocessLauncher = cast(GSubprocessLauncher*)obj; 72 super.setStruct(obj); 73 } 74 75 /** 76 * Sets our main struct and passes it to the parent class. 77 */ 78 public this (GSubprocessLauncher* gSubprocessLauncher, bool ownedRef = false) 79 { 80 this.gSubprocessLauncher = gSubprocessLauncher; 81 super(cast(GObject*)gSubprocessLauncher, ownedRef); 82 } 83 84 85 /** */ 86 public static GType getType() 87 { 88 return g_subprocess_launcher_get_type(); 89 } 90 91 /** 92 * Creates a new #GSubprocessLauncher. 93 * 94 * The launcher is created with the default options. A copy of the 95 * environment of the calling process is made at the time of this call 96 * and will be used as the environment that the process is launched in. 97 * 98 * Params: 99 * flags = #GSubprocessFlags 100 * 101 * Since: 2.40 102 * 103 * Throws: ConstructionException GTK+ fails to create the object. 104 */ 105 public this(GSubprocessFlags flags) 106 { 107 auto p = g_subprocess_launcher_new(flags); 108 109 if(p is null) 110 { 111 throw new ConstructionException("null returned by new"); 112 } 113 114 this(cast(GSubprocessLauncher*) p, true); 115 } 116 117 /** 118 * Returns the value of the environment variable @variable in the 119 * environment of processes launched from this launcher. 120 * 121 * On UNIX, the returned string can be an arbitrary byte string. 122 * On Windows, it will be UTF-8. 123 * 124 * Params: 125 * variable = the environment variable to get 126 * 127 * Returns: the value of the environment variable, %NULL if unset 128 * 129 * Since: 2.40 130 */ 131 public string getenv(string variable) 132 { 133 return Str.toString(g_subprocess_launcher_getenv(gSubprocessLauncher, Str.toStringz(variable))); 134 } 135 136 /** 137 * Sets up a child setup function. 138 * 139 * The child setup function will be called after fork() but before 140 * exec() on the child's side. 141 * 142 * @destroy_notify will not be automatically called on the child's side 143 * of the fork(). It will only be called when the last reference on the 144 * #GSubprocessLauncher is dropped or when a new child setup function is 145 * given. 146 * 147 * %NULL can be given as @child_setup to disable the functionality. 148 * 149 * Child setup functions are only available on UNIX. 150 * 151 * Params: 152 * childSetup = a #GSpawnChildSetupFunc to use as the child setup function 153 * userData = user data for @child_setup 154 * destroyNotify = a #GDestroyNotify for @user_data 155 * 156 * Since: 2.40 157 */ 158 public void setChildSetup(GSpawnChildSetupFunc childSetup, void* userData, GDestroyNotify destroyNotify) 159 { 160 g_subprocess_launcher_set_child_setup(gSubprocessLauncher, childSetup, userData, destroyNotify); 161 } 162 163 /** 164 * Sets the current working directory that processes will be launched 165 * with. 166 * 167 * By default processes are launched with the current working directory 168 * of the launching process at the time of launch. 169 * 170 * Params: 171 * cwd = the cwd for launched processes 172 * 173 * Since: 2.40 174 */ 175 public void setCwd(string cwd) 176 { 177 g_subprocess_launcher_set_cwd(gSubprocessLauncher, Str.toStringz(cwd)); 178 } 179 180 /** 181 * Replace the entire environment of processes launched from this 182 * launcher with the given 'environ' variable. 183 * 184 * Typically you will build this variable by using g_listenv() to copy 185 * the process 'environ' and using the functions g_environ_setenv(), 186 * g_environ_unsetenv(), etc. 187 * 188 * As an alternative, you can use g_subprocess_launcher_setenv(), 189 * g_subprocess_launcher_unsetenv(), etc. 190 * 191 * Pass an empty array to set an empty environment. Pass %NULL to inherit the 192 * parent process’ environment. As of GLib 2.54, the parent process’ environment 193 * will be copied when g_subprocess_launcher_set_environ() is called. 194 * Previously, it was copied when the subprocess was executed. This means the 195 * copied environment may now be modified (using g_subprocess_launcher_setenv(), 196 * etc.) before launching the subprocess. 197 * 198 * On UNIX, all strings in this array can be arbitrary byte strings. 199 * On Windows, they should be in UTF-8. 200 * 201 * Params: 202 * env = the replacement environment 203 * 204 * Since: 2.40 205 */ 206 public void setEnviron(string[] env) 207 { 208 g_subprocess_launcher_set_environ(gSubprocessLauncher, Str.toStringzArray(env)); 209 } 210 211 /** 212 * Sets the flags on the launcher. 213 * 214 * The default flags are %G_SUBPROCESS_FLAGS_NONE. 215 * 216 * You may not set flags that specify conflicting options for how to 217 * handle a particular stdio stream (eg: specifying both 218 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and 219 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT). 220 * 221 * You may also not set a flag that conflicts with a previous call to a 222 * function like g_subprocess_launcher_set_stdin_file_path() or 223 * g_subprocess_launcher_take_stdout_fd(). 224 * 225 * Params: 226 * flags = #GSubprocessFlags 227 * 228 * Since: 2.40 229 */ 230 public void setFlags(GSubprocessFlags flags) 231 { 232 g_subprocess_launcher_set_flags(gSubprocessLauncher, flags); 233 } 234 235 /** 236 * Sets the file path to use as the stderr for spawned processes. 237 * 238 * If @path is %NULL then any previously given path is unset. 239 * 240 * The file will be created or truncated when the process is spawned, as 241 * would be the case if using '2>' at the shell. 242 * 243 * If you want to send both stdout and stderr to the same file then use 244 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. 245 * 246 * You may not set a stderr file path if a stderr fd is already set or 247 * if the launcher flags contain any flags directing stderr elsewhere. 248 * 249 * This feature is only available on UNIX. 250 * 251 * Params: 252 * path = a filename or %NULL 253 * 254 * Since: 2.40 255 */ 256 public void setStderrFilePath(string path) 257 { 258 g_subprocess_launcher_set_stderr_file_path(gSubprocessLauncher, Str.toStringz(path)); 259 } 260 261 /** 262 * Sets the file path to use as the stdin for spawned processes. 263 * 264 * If @path is %NULL then any previously given path is unset. 265 * 266 * The file must exist or spawning the process will fail. 267 * 268 * You may not set a stdin file path if a stdin fd is already set or if 269 * the launcher flags contain any flags directing stdin elsewhere. 270 * 271 * This feature is only available on UNIX. 272 * 273 * Since: 2.40 274 */ 275 public void setStdinFilePath(string path) 276 { 277 g_subprocess_launcher_set_stdin_file_path(gSubprocessLauncher, Str.toStringz(path)); 278 } 279 280 /** 281 * Sets the file path to use as the stdout for spawned processes. 282 * 283 * If @path is %NULL then any previously given path is unset. 284 * 285 * The file will be created or truncated when the process is spawned, as 286 * would be the case if using '>' at the shell. 287 * 288 * You may not set a stdout file path if a stdout fd is already set or 289 * if the launcher flags contain any flags directing stdout elsewhere. 290 * 291 * This feature is only available on UNIX. 292 * 293 * Params: 294 * path = a filename or %NULL 295 * 296 * Since: 2.40 297 */ 298 public void setStdoutFilePath(string path) 299 { 300 g_subprocess_launcher_set_stdout_file_path(gSubprocessLauncher, Str.toStringz(path)); 301 } 302 303 /** 304 * Sets the environment variable @variable in the environment of 305 * processes launched from this launcher. 306 * 307 * On UNIX, both the variable's name and value can be arbitrary byte 308 * strings, except that the variable's name cannot contain '='. 309 * On Windows, they should be in UTF-8. 310 * 311 * Params: 312 * variable = the environment variable to set, must not contain '=' 313 * value = the new value for the variable 314 * overwrite = whether to change the variable if it already exists 315 * 316 * Since: 2.40 317 */ 318 public void setenv(string variable, string value, bool overwrite) 319 { 320 g_subprocess_launcher_setenv(gSubprocessLauncher, Str.toStringz(variable), Str.toStringz(value), overwrite); 321 } 322 323 /** 324 * Creates a #GSubprocess given a provided array of arguments. 325 * 326 * Params: 327 * argv = Command line arguments 328 * 329 * Returns: A new #GSubprocess, or %NULL on error (and @error will be set) 330 * 331 * Since: 2.40 332 * 333 * Throws: GException on failure. 334 */ 335 public Subprocess spawnv(string[] argv) 336 { 337 GError* err = null; 338 339 auto p = g_subprocess_launcher_spawnv(gSubprocessLauncher, Str.toStringzArray(argv), &err); 340 341 if (err !is null) 342 { 343 throw new GException( new ErrorG(err) ); 344 } 345 346 if(p is null) 347 { 348 return null; 349 } 350 351 return ObjectG.getDObject!(Subprocess)(cast(GSubprocess*) p, true); 352 } 353 354 /** 355 * Transfer an arbitrary file descriptor from parent process to the 356 * child. This function takes "ownership" of the fd; it will be closed 357 * in the parent when @self is freed. 358 * 359 * By default, all file descriptors from the parent will be closed. 360 * This function allows you to create (for example) a custom pipe() or 361 * socketpair() before launching the process, and choose the target 362 * descriptor in the child. 363 * 364 * An example use case is GNUPG, which has a command line argument 365 * --passphrase-fd providing a file descriptor number where it expects 366 * the passphrase to be written. 367 * 368 * Params: 369 * sourceFd = File descriptor in parent process 370 * targetFd = Target descriptor for child process 371 */ 372 public void takeFd(int sourceFd, int targetFd) 373 { 374 g_subprocess_launcher_take_fd(gSubprocessLauncher, sourceFd, targetFd); 375 } 376 377 /** 378 * Sets the file descriptor to use as the stderr for spawned processes. 379 * 380 * If @fd is -1 then any previously given fd is unset. 381 * 382 * Note that the default behaviour is to pass stderr through to the 383 * stderr of the parent process. 384 * 385 * The passed @fd belongs to the #GSubprocessLauncher. It will be 386 * automatically closed when the launcher is finalized. The file 387 * descriptor will also be closed on the child side when executing the 388 * spawned process. 389 * 390 * You may not set a stderr fd if a stderr file path is already set or 391 * if the launcher flags contain any flags directing stderr elsewhere. 392 * 393 * This feature is only available on UNIX. 394 * 395 * Params: 396 * fd = a file descriptor, or -1 397 * 398 * Since: 2.40 399 */ 400 public void takeStderrFd(int fd) 401 { 402 g_subprocess_launcher_take_stderr_fd(gSubprocessLauncher, fd); 403 } 404 405 /** 406 * Sets the file descriptor to use as the stdin for spawned processes. 407 * 408 * If @fd is -1 then any previously given fd is unset. 409 * 410 * Note that if your intention is to have the stdin of the calling 411 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT 412 * is a better way to go about doing that. 413 * 414 * The passed @fd is noted but will not be touched in the current 415 * process. It is therefore necessary that it be kept open by the 416 * caller until the subprocess is spawned. The file descriptor will 417 * also not be explicitly closed on the child side, so it must be marked 418 * O_CLOEXEC if that's what you want. 419 * 420 * You may not set a stdin fd if a stdin file path is already set or if 421 * the launcher flags contain any flags directing stdin elsewhere. 422 * 423 * This feature is only available on UNIX. 424 * 425 * Params: 426 * fd = a file descriptor, or -1 427 * 428 * Since: 2.40 429 */ 430 public void takeStdinFd(int fd) 431 { 432 g_subprocess_launcher_take_stdin_fd(gSubprocessLauncher, fd); 433 } 434 435 /** 436 * Sets the file descriptor to use as the stdout for spawned processes. 437 * 438 * If @fd is -1 then any previously given fd is unset. 439 * 440 * Note that the default behaviour is to pass stdout through to the 441 * stdout of the parent process. 442 * 443 * The passed @fd is noted but will not be touched in the current 444 * process. It is therefore necessary that it be kept open by the 445 * caller until the subprocess is spawned. The file descriptor will 446 * also not be explicitly closed on the child side, so it must be marked 447 * O_CLOEXEC if that's what you want. 448 * 449 * You may not set a stdout fd if a stdout file path is already set or 450 * if the launcher flags contain any flags directing stdout elsewhere. 451 * 452 * This feature is only available on UNIX. 453 * 454 * Params: 455 * fd = a file descriptor, or -1 456 * 457 * Since: 2.40 458 */ 459 public void takeStdoutFd(int fd) 460 { 461 g_subprocess_launcher_take_stdout_fd(gSubprocessLauncher, fd); 462 } 463 464 /** 465 * Removes the environment variable @variable from the environment of 466 * processes launched from this launcher. 467 * 468 * On UNIX, the variable's name can be an arbitrary byte string not 469 * containing '='. On Windows, it should be in UTF-8. 470 * 471 * Params: 472 * variable = the environment variable to unset, must not contain '=' 473 * 474 * Since: 2.40 475 */ 476 public void unsetenv(string variable) 477 { 478 g_subprocess_launcher_unsetenv(gSubprocessLauncher, Str.toStringz(variable)); 479 } 480 }