Commit c575d24d authored by Matthias Clasen's avatar Matthias Clasen

Docs: Don't use the note tag

More markup avoidance.
parent 4cbee6a3
......@@ -29,14 +29,12 @@
* @short_description: I/O Scheduler
* @include: gio/gio.h
*
* <note><para>
* As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
* are deprecated in favor of #GThreadPool and #GTask.
* </para></note>
* As of GLib 2.36, #GIOScheduler is deprecated in favor of
* #GThreadPool and #GTask.
*
* Schedules asynchronous I/O operations. #GIOScheduler integrates
* into the main event loop (#GMainLoop) and uses threads.
**/
*/
struct _GIOSchedulerJob {
GList *active_link;
......
......@@ -75,13 +75,11 @@ static gboolean g_settings_has_backend;
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
*
* <note><para>
* The #GSettingsBackend API is exported to allow third-party
* The GSettingsBackend API is exported to allow third-party
* implementations, but does not carry the same stability guarantees
* as the public GIO API. For this reason, you have to define the
* C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
* C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
* <filename>gio/gsettingsbackend.h</filename>
* </para></note>
**/
static gboolean
......
......@@ -34,12 +34,10 @@
* SECTION:gsimpleasyncresult
* @short_description: Simple asynchronous results implementation
* @include: gio/gio.h
* @see_also: #GAsyncResult
* @see_also: #GAsyncResult, #GTask
*
* <note><para>
* As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
* #GTask, which provides a simpler API.
* </para></note>
* As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
* #GTask, which provides a simpler API.
*
* #GSimpleAsyncResult implements #GAsyncResult.
*
......
......@@ -390,10 +390,8 @@ g_themed_icon_get_names (GThemedIcon *icon)
*
* Append a name to the list of icons from within @icon.
*
* <note><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
* </para></note>
*/
void
g_themed_icon_append_name (GThemedIcon *icon,
......@@ -419,10 +417,8 @@ g_themed_icon_append_name (GThemedIcon *icon,
*
* Prepend a name to the list of icons from within @icon.
*
* <note><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
* </para></note>
*
* Since: 2.18
*/
......
This diff is collapsed.
This diff is collapsed.
......@@ -520,11 +520,11 @@ g_dngettext (const gchar *domain,
* See the C_() macro for a different way to mark up translatable strings
* with context.
*
* <note><para>If you are using the Q_() macro, you need to make sure
* that you pass <option>--keyword=Q_</option> to xgettext when extracting
* messages. If you are using GNU gettext >= 0.15, you can also use
* If you are using the Q_() macro, you need to make sure that you pass
* <option>--keyword=Q_</option> to xgettext when extracting messages.
* If you are using GNU gettext >= 0.15, you can also use
* <option>--keyword=Q_:1g</option> to let xgettext split the context
* string off into a msgctxt line in the po file.</para></note>
* string off into a msgctxt line in the po file.
*
* Returns: the translated message
*
......@@ -545,10 +545,9 @@ g_dngettext (const gchar *domain,
* label2 = C_("Body part", "Back");
* ]|
*
* <note><para>If you are using the C_() macro, you need to make sure
* that you pass <option>--keyword=C_:1c,2</option> to xgettext when
* extracting messages. Note that this only works with GNU
* gettext >= 0.15.</para></note>
* If you are using the C_() macro, you need to make sure that you pass
* <option>--keyword=C_:1c,2</option> to xgettext when extracting messages.
* Note that this only works with GNU gettext >= 0.15.
*
* Returns: the translated message
*
......@@ -609,11 +608,10 @@ g_dngettext (const gchar *domain,
* }
* ]|
*
* <note><para>If you are using the NC_() macro, you need to make sure
* that you pass <option>--keyword=NC_:1c,2</option> to xgettext when
* extracting messages. Note that this only works with GNU gettext >= 0.15.
* Intltool has support for the NC_() macro since version 0.40.1.
* </para></note>
* If you are using the NC_() macro, you need to make sure that you pass
* <option>--keyword=NC_:1c,2</option> to xgettext when extracting messages.
* Note that this only works with GNU gettext >= 0.15. Intltool has support
* for the NC_() macro since version 0.40.1.
*
* Since: 2.18
*/
......
......@@ -3561,16 +3561,15 @@ g_key_file_has_key_full (GKeyFile *key_file,
* Looks whether the key file has the key @key in the group
* @group_name.
*
* <note>This function does not follow the rules for #GError strictly;
* Note that this function does not follow the rules for #GError strictly;
* the return value both carries meaning and signals an error. To use
* this function, you must pass a #GError pointer in @error, and check
* whether it is not %NULL to see if an error occurred.</note>
* whether it is not %NULL to see if an error occurred.
*
* Language bindings should use g_key_file_get_value() to test whether
* or not a key exists.
*
* Return value: %TRUE if @key is a part of @group_name, %FALSE
* otherwise.
* Return value: %TRUE if @key is a part of @group_name, %FALSE otherwise
*
* Since: 2.6
**/
......
......@@ -63,19 +63,17 @@ g_unix_set_error_from_errno (GError **error,
/**
* g_unix_open_pipe:
* @fds: Array of two integers
* @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
* @flags: Bitfield of file descriptor flags, as for fcntl()
* @error: a #GError
*
* Similar to the UNIX pipe() call, but on modern systems like Linux
* uses the pipe2() system call, which atomically creates a pipe with
* the configured flags. The only supported flag currently is
* <literal>FD_CLOEXEC</literal>. If for example you want to configure
* <literal>O_NONBLOCK</literal>, that must still be done separately with
* fcntl().
* the configured flags. The only supported flag currently is
* %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
* must still be done separately with fcntl().
*
* <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
* <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
* different on Linux/glibc.</note>
* This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
* for fcntl(); these are different on Linux/glibc.
*
* Returns: %TRUE on success, %FALSE if not (and errno will be set).
*
......@@ -138,8 +136,8 @@ g_unix_open_pipe (int *fds,
* @error: a #GError
*
* Control the non-blocking state of the given file descriptor,
* according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
* on some older ones may use <literal>O_NDELAY</literal>.
* according to @nonblock. On most systems this uses %O_NONBLOCK, but
* on some older ones may use %O_NDELAY.
*
* Returns: %TRUE if successful
*
......
......@@ -174,13 +174,10 @@ g_list_alloc (void)
* @list: a #GList
*
* Frees all of the memory used by a #GList.
* The freed elements are returned to the slice allocator
* The freed elements are returned to the slice allocator.
*
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_list_free_full() or free them manually
* first.
* </para></note>
* If list elements contain dynamically-allocated memory, you should
* either use g_list_free_full() or free them manually first.
*/
void
g_list_free (GList *list)
......@@ -299,10 +296,8 @@ g_list_append (GList *list,
* list = g_list_prepend (list, "first");
* ]|
*
* <note><para>
* Do not use this function to prepend a new element to a different element
* than the start of the list. Use g_list_insert_before() instead.
* </para></note>
* Do not use this function to prepend a new element to a different
* element than the start of the list. Use g_list_insert_before() instead.
*
* Returns: a pointer to the newly prepended element, which is the new
* start of the #GList
......@@ -625,12 +620,10 @@ g_list_delete_link (GList *list,
*
* Copies a #GList.
*
* <note><para>
* Note that this is a "shallow" copy. If the list elements
* consist of pointers to data, the pointers are copied but
* the actual data is not. See g_list_copy_deep() if you need
* to copy the data as well.
* </para></note>
*
* Returns: the start of the new list that holds the same data as @list
*/
......@@ -955,11 +948,9 @@ g_list_first (GList *list)
*
* Gets the number of elements in a #GList.
*
* <note><para>
* This function iterates over the whole list to count its elements.
* Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
* of a GList if you regularly need the number of items.
* </para></note>
* Use a #GQueue instead of a GList if you regularly need the number
* of items.
*
* Returns: the number of elements in the #GList
*/
......@@ -1071,12 +1062,10 @@ g_list_insert_sorted_real (GList *list,
* Inserts a new element into the list, using the given comparison
* function to determine its position.
*
* <note><para>
* If you are adding many new elements to a list, and the number of
* new elements is much larger than the length of the list, use
* g_list_prepend() to add the new items and sort the list afterwards
* with g_list_sort()
* </para></note>
* with g_list_sort().
*
* Returns: the (possibly changed) start of the #GList
*/
......@@ -1101,12 +1090,10 @@ g_list_insert_sorted (GList *list,
* Inserts a new element into the list, using the given comparison
* function to determine its position.
*
* <note><para>
* If you are adding many new elements to a list, and the number of
* new elements is much larger than the length of the list, use
* g_list_prepend() to add the new items and sort the list afterwards
* with g_list_sort()
* </para></note>
* with g_list_sort().
*
* Returns: the (possibly changed) start of the #GList
*
......
......@@ -42,18 +42,16 @@
* "long long" types even in the presence of '-ansi -pedantic'.
*/
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 8)
# define G_GNUC_EXTENSION __extension__
#define G_GNUC_EXTENSION __extension__
#else
# define G_GNUC_EXTENSION
#define G_GNUC_EXTENSION
#endif
/* Provide macros to feature the GCC function attribute.
*/
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
#define G_GNUC_PURE \
__attribute__((__pure__))
#define G_GNUC_MALLOC \
__attribute__((__malloc__))
#define G_GNUC_PURE __attribute__((__pure__))
#define G_GNUC_MALLOC __attribute__((__malloc__))
#else
#define G_GNUC_PURE
#define G_GNUC_MALLOC
......@@ -99,8 +97,7 @@
#endif /* !__GNUC__ */
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
#define G_GNUC_DEPRECATED \
__attribute__((__deprecated__))
#define G_GNUC_DEPRECATED __attribute__((__deprecated__))
#else
#define G_GNUC_DEPRECATED
#endif /* __GNUC__ */
......@@ -130,14 +127,13 @@
#endif
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
# define G_GNUC_MAY_ALIAS __attribute__((may_alias))
#define G_GNUC_MAY_ALIAS __attribute__((may_alias))
#else
# define G_GNUC_MAY_ALIAS
#define G_GNUC_MAY_ALIAS
#endif
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#define G_GNUC_WARN_UNUSED_RESULT \
__attribute__((warn_unused_result))
#define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
#else
#define G_GNUC_WARN_UNUSED_RESULT
#endif /* __GNUC__ */
......@@ -185,29 +181,29 @@
/* Provide a string identifying the current code position */
#if defined(__GNUC__) && (__GNUC__ < 3) && !defined(__cplusplus)
# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
#else
# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__)
#define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__)
#endif
/* Provide a string identifying the current function, non-concatenatable */
#if defined (__GNUC__) && defined (__cplusplus)
# define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__))
#define G_STRFUNC ((const char*) (__PRETTY_FUNCTION__))
#elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
# define G_STRFUNC ((const char*) (__func__))
#define G_STRFUNC ((const char*) (__func__))
#elif defined (__GNUC__) || (defined(_MSC_VER) && (_MSC_VER > 1300))
# define G_STRFUNC ((const char*) (__FUNCTION__))
#define G_STRFUNC ((const char*) (__FUNCTION__))
#else
# define G_STRFUNC ((const char*) ("???"))
#define G_STRFUNC ((const char*) ("???"))
#endif
/* Guard C code in headers, while including them from C++ */
#ifdef __cplusplus
# define G_BEGIN_DECLS extern "C" {
# define G_END_DECLS }
#define G_BEGIN_DECLS extern "C" {
#define G_END_DECLS }
#else
# define G_BEGIN_DECLS
# define G_END_DECLS
#define G_BEGIN_DECLS
#define G_END_DECLS
#endif
/* Provide definitions for some commonly used macros.
......@@ -217,9 +213,9 @@
*/
#ifndef NULL
# ifdef __cplusplus
# define NULL (0L)
# define NULL (0L)
# else /* !__cplusplus */
# define NULL ((void*) 0)
# define NULL ((void*) 0)
# endif /* !__cplusplus */
#endif
......@@ -259,10 +255,10 @@
*/
#if defined(__GNUC__) && __GNUC__ >= 4
# define G_STRUCT_OFFSET(struct_type, member) \
#define G_STRUCT_OFFSET(struct_type, member) \
((glong) offsetof (struct_type, member))
#else
# define G_STRUCT_OFFSET(struct_type, member) \
#define G_STRUCT_OFFSET(struct_type, member) \
((glong) ((guint8*) &((struct_type*) 0)->member))
#endif
......@@ -279,8 +275,8 @@
* avoid portability issue or side effects when compiled with different compilers.
*/
#if !(defined (G_STMT_START) && defined (G_STMT_END))
# define G_STMT_START do
# define G_STMT_END while (0)
#define G_STMT_START do
#define G_STMT_END while (0)
#endif
/* Deprecated -- do not use. */
......
......@@ -66,18 +66,15 @@ static GMemVTable glib_mem_vtable = {
*
* These functions provide support for allocating and freeing memory.
*
* <note>
* If any call to allocate memory fails, the application is terminated.
* This also means that there is no need to check if the call succeeded.
* </note>
*
* <note>
* It's important to match g_malloc() with g_free(), plain malloc() with free(),
* and (if you're using C++) new with delete and new[] with delete[]. Otherwise
* bad things can happen, since these allocators may use different memory
* pools (and new/delete call constructors and destructors). See also
* g_mem_set_vtable().
* </note>
*
* It's important to match g_malloc() (and wrappers such as g_new()) with
* g_free(), g_slice_alloc() and wrappers such as g_slice_new()) with
* g_slice_free(), plain malloc() with free(), and (if you're using C++)
* new with delete and new[] with delete[]. Otherwise bad things can happen,
* since these allocators may use different memory pools (and new/delete call
* constructors and destructors). See also g_mem_set_vtable().
*/
/* --- functions --- */
......
......@@ -75,11 +75,8 @@ g_queue_new (void)
* if @queue was created with g_queue_new(). If queue elements contain
* dynamically-allocated memory, they should be freed first.
*
* <note><para>
* If queue elements contain dynamically-allocated memory,
* you should either use g_queue_free_full() or free them manually
* first.
* </para></note>
* If queue elements contain dynamically-allocated memory, you should
* either use g_queue_free_full() or free them manually first.
**/
void
g_queue_free (GQueue *queue)
......
......@@ -769,13 +769,11 @@ g_sequence_sort_changed (GSequenceIter *iter,
* If you are simply searching for an existing element of the sequence,
* consider using g_sequence_lookup().
*
* <note><para>
* This function will fail if the data contained in the sequence is
* unsorted. Use g_sequence_insert_sorted() or
* g_sequence_insert_sorted_iter() to add data to your sequence or, if
* you want to add a large amount of data, call g_sequence_sort() after
* doing unsorted insertions.
* </para></note>
*
* Return value: an #GSequenceIter pointing to the position where @data
* would have been inserted according to @cmp_func and @cmp_data.
......@@ -818,13 +816,11 @@ g_sequence_search (GSequence *seq,
* the first item comes before the second, and a positive value if
* the second item comes before the first.
*
* <note><para>
* This function will fail if the data contained in the sequence is
* unsorted. Use g_sequence_insert_sorted() or
* g_sequence_insert_sorted_iter() to add data to your sequence or, if
* you want to add a large amount of data, call g_sequence_sort() after
* doing unsorted insertions.
* </para></note>
*
* Return value: an #GSequenceIter pointing to the position of the
* first item found equal to @data according to @cmp_func and
......@@ -1052,13 +1048,11 @@ g_sequence_insert_sorted_iter (GSequence *seq,
* If you are simply searching for an existing element of the sequence,
* consider using g_sequence_lookup_iter().
*
* <note><para>
* This function will fail if the data contained in the sequence is
* unsorted. Use g_sequence_insert_sorted() or
* g_sequence_insert_sorted_iter() to add data to your sequence or, if
* you want to add a large amount of data, call g_sequence_sort() after
* doing unsorted insertions.
* </para></note>
*
* Return value: a #GSequenceIter pointing to the position in @seq
* where @data would have been inserted according to @iter_cmp
......@@ -1112,13 +1106,11 @@ g_sequence_search_iter (GSequence *seq,
* if the first iterator comes before the second, and a positive
* value if the second iterator comes before the first.
*
* <note><para>
* This function will fail if the data contained in the sequence is
* unsorted. Use g_sequence_insert_sorted() or
* g_sequence_insert_sorted_iter() to add data to your sequence or, if
* you want to add a large amount of data, call g_sequence_sort() after
* doing unsorted insertions.
* </para></note>
*
* Return value: an #GSequenceIter pointing to the position of
* the first item found equal to @data according to @cmp_func
......
......@@ -128,11 +128,9 @@ g_slist_alloc (void)
* Frees all of the memory used by a #GSList.
* The freed elements are returned to the slice allocator.
*
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_slist_free_full() or free them manually
* first.
* </para></note>
*/
void
g_slist_free (GSList *list)
......@@ -185,17 +183,13 @@ g_slist_free_full (GSList *list,
*
* Adds a new element on to the end of the list.
*
* <note><para>
* The return value is the new start of the list, which may
* have changed, so make sure you store the new value.
* </para></note>
*
* <note><para>
* Note that g_slist_append() has to traverse the entire list
* to find the end, which is inefficient when adding multiple
* elements. A common idiom to avoid the inefficiency is to prepend
* the elements and reverse the list when all elements have been added.
* </para></note>
*
* |[
* /&ast; Notice that these are initialized to the empty list. &ast;/
......@@ -242,10 +236,8 @@ g_slist_append (GSList *list,
*
* Adds a new element on to the start of the list.
*
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
*
* |[
* /&ast; Notice that it is initialized to the empty list. &ast;/
......@@ -515,11 +507,11 @@ _g_slist_remove_link (GSList *list,
* link is set to %NULL, so that it becomes a
* self-contained list with one element.
*
* <note>Removing arbitrary nodes from a singly-linked list
* Removing arbitrary nodes from a singly-linked list
* requires time that is proportional to the length of the list
* (ie. O(n)). If you find yourself using g_slist_remove_link()
* frequently, you should consider a different data structure, such
* as the doubly-linked #GList.</note>
* frequently, you should consider a different data structure,
* such as the doubly-linked #GList.
*
* Returns: the new start of the #GSList, without the element
*/
......@@ -539,11 +531,11 @@ g_slist_remove_link (GSList *list,
* Compare this to g_slist_remove_link() which removes the node
* without freeing it.
*
* <note>Removing arbitrary nodes from a singly-linked list
* requires time that is proportional to the length of the list
* (ie. O(n)). If you find yourself using g_slist_delete_link()
* frequently, you should consider a different data structure, such
* as the doubly-linked #GList.</note>
* Removing arbitrary nodes from a singly-linked list requires time
* that is proportional to the length of the list (ie. O(n)). If you
* find yourself using g_slist_delete_link() frequently, you should
* consider a different data structure, such as the doubly-linked
* #GList.
*
* Returns: the new head of @list
*/
......@@ -563,12 +555,10 @@ g_slist_delete_link (GSList *list,
*
* Copies a #GSList.
*
* <note><para>
* Note that this is a "shallow" copy. If the list elements
* consist of pointers to data, the pointers are copied but
* the actual data isn't. See g_slist_copy_deep() if you need
* to copy the data as well.
* </para></note>
*
* Returns: a copy of @list
*/
......@@ -828,9 +818,7 @@ g_slist_index (GSList *list,
*
* Gets the last element in a #GSList.
*
* <note><para>
* This function iterates over the whole list.
* </para></note>
*
* Returns: the last element in the #GSList,
* or %NULL if the #GSList has no elements
......@@ -853,10 +841,8 @@ g_slist_last (GSList *list)
*
* Gets the number of elements in a #GSList.
*
* <note><para>
* This function iterates over the whole list to
* count its elements.
* </para></note>
*
* Returns: the number of elements in the #GSList
*/
......
......@@ -109,17 +109,14 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
* 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
* are spawning is a graphical application, too, then you may
* want to use gdk_spawn_on_screen() instead to ensure that
* the spawned program opens its windows on the right screen.
* </para></note>
* If you are writing a GTK+ application, and the program you are
* spawning is a graphical application, too, then you may want to
* use gdk_spawn_on_screen() instead to ensure that the spawned program
* opens its windows on the right screen.
*
* <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>
* 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.
*
* Return value: %TRUE on success, %FALSE if error is set
**/
......@@ -237,8 +234,8 @@ read_data (GString *str,
* function for full details on the other parameters and details on
* how these functions work on Windows.
*
* Return value: %TRUE on success, %FALSE if an error was set.
**/
* Return value: %TRUE on success, %FALSE if an error was set
*/
gboolean
g_spawn_sync (const gchar *working_directory,
gchar **argv,
......@@ -509,21 +506,19 @@ g_spawn_sync (const gchar *working_directory,
* level wide character command line passed to the spawned program
* using the GetCommandLineW() function.
*
* On Windows the low-level child process creation API
* <function>CreateProcess()</function> doesn't use argument vectors,
* but a command line. The C runtime library's
* <function>spawn*()</function> family of functions (which
* g_spawn_async_with_pipes() eventually calls) paste the argument
* vector elements together into a command line, and the C runtime startup code
* does a corresponding reconstruction of an argument vector from the
* command line, to be passed to main(). Complications arise when you have
* argument vector elements that contain spaces of double quotes. The
* <function>spawn*()</function> functions don't do any quoting or
* escaping, but on the other hand the startup code does do unquoting
* and unescaping in order to enable receiving arguments with embedded
* spaces or double quotes. To work around this asymmetry,
* g_spawn_async_with_pipes() will do quoting and escaping on argument
* vector elements that need it before calling the C runtime
* On Windows the low-level child process creation API CreateProcess()
* doesn't use argument vectors, but a command line. The C runtime
* library's spawn*() family of functions (which g_spawn_async_with_pipes()
* eventually calls) paste the argument vector elements together into
* a command line, and the C runtime startup code does a corresponding
* reconstruction of an argument vector from the command line, to be
* passed to main(). Complications arise when you have argument vector
* elements that contain spaces of double quotes. The spawn*() functions
* don't do any quoting or escaping, but on the other hand the startup
* code does do unquoting and unescaping in order to enable receiving
* arguments with embedded spaces or double quotes. To work around this
* asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
* argument vector elements that need it before calling the C runtime
* spawn() function.
*
* The returned @child_pid on Windows is a handle to the child
......@@ -542,20 +537,19 @@ g_spawn_sync (const gchar *working_directory,
* call g_spawn_close_pid() on the @child_pid, in order to free
* resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling
* the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
* the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned
* in @child_pid). See g_child_watch_add().
* in @child_pid). See g_child_watch_add().
*
* %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
* descriptors will be inherited by the child; otherwise all
* descriptors except stdin/stdout/stderr will be closed before
* calling exec() in the child. %G_SPAWN_SEARCH_PATH
* means that <literal>argv[0]</literal> need not be an absolute path, it
* will be looked for in the <envar>PATH</envar> environment variable.
* %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it
* will be looked for in the <envar>PATH</envar> variable from @envp. If
* both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP are used,
* the value from @envp takes precedence over the environment.
* descriptors will be inherited by the child; otherwise all descriptors
* except stdin/stdout/stderr will be closed before calling exec() in the
* child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an absolute
* path, it will be looked for in the <envar>PATH</envar> environment
* variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute
* path, it will be looked for in the <envar>PATH</envar> variable from
* @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
* are used, the value from @envp takes precedence over the environment.
* %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will
* be discarded, instead of going to the same location as the parent's
* standard output. If you use this flag, @standard_output must be %NULL.
......@@ -566,42 +560,40 @@ g_spawn_sync (const gchar *working_directory,
* standard input (by default, the child's standard input is attached to
* /dev/null). If you use this flag, @standard_input must be %NULL.
* %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
* the file to execute, while the remaining elements are the
* actual argument vector to pass to the file. Normally
* g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and
* passes all of @argv to the child.
* the file to execute, while the remaining elements are the actual
* argument vector to pass to the file. Normally g_spawn_async_with_pipes()
* uses @argv[0] as the file to execute, and passes all of @argv to the child.
*
* @child_setup and @user_data are a function and user data. On POSIX
* platforms, the function is called in the child after GLib has
* performed all the setup it plans to perform (including creating
* pipes, closing file descriptors, etc.) but before calling
* exec(). That is, @child_setup is called just
* before calling exec() in the child. Obviously
* actions taken in this function will only affect the child, not the
* parent.
* pipes, closing file descriptors, etc.) but before calling exec().
* That is, @child_setup is called just before calling exec() in the
* child. Obviously actions taken in this function will only affect
* the child, not the parent.
*
* On Windows, there is no separate fork() and exec()
* functionality. Child processes are created and run with a single
* API call, CreateProcess(). There is no sensible thing @child_setup
* On Windows, there is no separate fork() and exec() functionality.
* Child processes are created and run with a single API call,
* CreateProcess(). There is no sensible thing @child_setup
* could be used for on Windows so it is ignored and not called.
*
* If non-%NULL, @child_pid will on Unix be filled with the child's
* process ID. You can use the process ID to send signals to the
* child, or to use g_child_watch_add() (or waitpid()) if you specified the
* process ID. You can use the process ID to send signals to the child,
* or to use g_child_watch_add() (or waitpid()) if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
* filled with a handle to the child process only if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
* process using the Win32 API, for example wait for its termination
* with the <function>WaitFor*()</function> functions, or examine its
* exit code with GetExitCodeProcess(). You should close the handle
* with CloseHandle() or g_spawn_close_pid() when you no longer need it.
* with the WaitFor*() functions, or examine its exit code with
* GetExitCodeProcess(). You should close the handle with CloseHandle()
* or g_spawn_close_pid() when you no longer need it.
*
* If non-%NULL, the @standard_input, @standard_output, @standard_error
* locations will be filled with file descriptors for writing to the child's
* standard input or reading from its standard output or standard error.
* The caller of g_spawn_async_with_pipes() must close these file descriptors
* when they are no longer in use. If these parameters are %NULL, the corresponding
* pipe won't be created.
* when they are no longer in use. If these parameters are %NULL, the
* corresponding pipe won't be created.
*
* If @standard_input is NULL, the child's standard input is attached to
* /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
......@@ -615,11 +607,11 @@ g_spawn_sync (const gchar *working_directory,
* is set.
*
* @error can be %NULL to ignore errors, or non-%NULL to report errors.
* If an error is set, the function returns %FALSE. Errors
* are reported even if they occur in the child (for example if the
* executable in <literal>argv[0]</literal> is not found). Typically
* the <literal>message</literal> field of returned errors should be displayed
* to users. Possible errors are those from the #G_SPAWN_ERROR domain.
* If an error is set, the function returns %FALSE. Errors are reported
* even if they occur in the child (for example if the executable in
* @argv[0] is not found). Typically the <literal>message</literal> field
* of returned errors should be displayed to users. Possible errors are
* those from the #G_SPAWN_ERROR domain.
*
* If an error occurs, @child_pid, @standard_input, @standard_output,
* and @standard_error will not be filled with valid values.
......@@ -627,15 +619,13 @@ g_spawn_sync (const gchar *working_directory,
* If @child_pid is not %NULL and an error does not occur then the returned
* process reference must be closed using g_spawn_close_pid().
*
* <note><para>
* If you are writing a GTK+ application, and the program you
* are spawning is a graphical application, too, then you may
* want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
* the spawned program opens its windows on the right screen.
* </para></note>
*
* Return value: %TRUE on success, %FALSE if an error was set
**/
*/
gboolean
g_spawn_async_with_pipes (const gchar *working_directory,
gchar **argv,
......@@ -759,7 +749,7 @@ g_spawn_command_line_sync (const gchar *command_line,
*
* The same concerns on Windows apply as for g_spawn_command_line_sync().