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