glib r6995 - in trunk: . glib

[tml svn gnome org]

Author: tml
Date: Wed Jun 11 06:57:22 2008
New Revision: 6995
URL: http://svn.gnome.org/viewvc/glib?rev=6995&view=rev

Log:
2008-06-11  Tor Lillqvist  <tml novell com>

	* glib/gmain.c
	* glib/gspawn.c: Clarify what a "child pid" is in the doc
	comments.



Modified:
   trunk/ChangeLog
   trunk/glib/gmain.c
   trunk/glib/gspawn.c

Modified: trunk/glib/gmain.c
==============================================================================
--- trunk/glib/gmain.c	(original)
+++ trunk/glib/gmain.c	Wed Jun 11 06:57:22 2008
@@ -4003,8 +4003,8 @@
 
 /**
  * g_child_watch_source_new:
- * @pid: process id of a child process to watch. On Windows, a HANDLE
- * for the process to watch (which actually doesn't have to be a child).
+ * @pid: process to watch. On POSIX the pid of a child process. On
+ * Windows a handle for a process (which doesn't have to be a child).
  * 
  * Creates a new child_watch source.
  *
@@ -4054,7 +4054,8 @@
  * g_child_watch_add_full:
  * @priority: the priority of the idle source. Typically this will be in the
  *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
- * @pid:      process id of a child process to watch
+ * @pid:      process to watch. On POSIX the pid of a child process. On
+ * Windows a handle for a process (which doesn't have to be a child).
  * @function: function to call
  * @data:     data to pass to @function
  * @notify:   function to call when the idle is removed, or %NULL
@@ -4103,7 +4104,8 @@
 
 /**
  * g_child_watch_add:
- * @pid:      process id of a child process to watch
+ * @pid:      process id to watch. On POSIX the pid of a child process. On
+ * Windows a handle for a process (which doesn't have to be a child).
  * @function: function to call
  * @data:     data to pass to @function
  * 

Modified: trunk/glib/gspawn.c
==============================================================================
--- trunk/glib/gspawn.c	(original)
+++ trunk/glib/gspawn.c	Wed Jun 11 06:57:22 2008
@@ -84,11 +84,14 @@
  * @flags: flags from #GSpawnFlags
  * @child_setup: function to run in the child just before exec()
  * @user_data: user data for @child_setup
- * @child_pid: return location for child process ID, or %NULL
+ * @child_pid: return location for child process reference, or %NULL
  * @error: return location for error
  * 
  * See g_spawn_async_with_pipes() for a full description; this function
  * simply calls the g_spawn_async_with_pipes() without any pipes.
+ *
+ * You should call g_spawn_close_pid() on the returned child process
+ * reference when you don't need it any more.
  * 
  * <note><para>
  * If you are writing a GTK+ application, and the program you 
@@ -97,6 +100,11 @@
  * the spawned program opens its windows on the right screen.
  * </para></note>
  *
+ * <note><para> Note that the returned @child_pid on Windows is a
+ * handle to the child process and not its identifier. Process handles
+ * and process identifiers are different concepts on Windows.
+ * </para></note>
+ *
  * Return value: %TRUE on success, %FALSE if error is set
  **/
 gboolean
@@ -485,6 +493,10 @@
  * vector elements that need it before calling the C runtime
  * spawn() function.
  *
+ * The returned @child_pid on Windows is a handle to the child
+ * process, not its identifier. Process handles and process
+ * identifiers are different concepts on Windows.
+ *
  * @envp is a %NULL-terminated array of strings, where each string
  * has the form <literal>KEY=VALUE</literal>. This will become
  * the child's environment. If @envp is %NULL, the child inherits its
@@ -577,7 +589,7 @@
  * and @standard_error will not be filled with valid values.
  *
  * If @child_pid is not %NULL and an error does not occur then the returned
- * pid must be closed using g_spawn_close_pid().
+ * process reference must be closed using g_spawn_close_pid().
  *
  * <note><para>
  * If you are writing a GTK+ application, and the program you 
@@ -1641,9 +1653,9 @@
 
 /**
  * g_spawn_close_pid:
- * @pid: The process identifier to close
+ * @pid: The process reference to close
  *
- * On some platforms, notably WIN32, the #GPid type represents a resource
+ * On some platforms, notably Windows, the #GPid type represents a resource
  * which must be closed to prevent resource leaking. g_spawn_close_pid()
  * is provided for this purpose. It should be used on all platforms, even
  * though it doesn't do anything under UNIX.