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