diff options
Diffstat (limited to 'gir/glib-2.0.c')
| -rw-r--r-- | gir/glib-2.0.c | 1093 |
1 files changed, 887 insertions, 206 deletions
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 2966d1b5..a01b5d27 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -429,7 +429,7 @@ * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the entire system. * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function. - * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a `SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see this code unless it has handled or blocked `SIGPIPE'. + * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a 'SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see this code unless it has handled or blocked 'SIGPIPE'. * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might work if you try again later. * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again. * @G_FILE_ERROR_IO: Input/output error; usually used for physical read or write errors. i.e. the disk or other physical device hardware is returning errors. @@ -1761,6 +1761,32 @@ /** + * GTestFileType: + * @G_TEST_DIST: a file that was included in the distribution tarball + * @G_TEST_BUILT: a file that was built on the compiling machine + * + * The type of file to return the filename for, when used with + * g_test_build_filename(). + * + * These two options correspond rather directly to the 'dist' and + * 'built' terminology that automake uses and are explicitly used to + * distinguish between the 'srcdir' and 'builddir' being separate. All + * files in your project should either be dist (in the + * <literal>DIST_EXTRA</literal> or <literal>dist_schema_DATA</literal> + * sense, in which case they will always be in the srcdir) or built (in + * the <literal>BUILT_SOURCES</literal> sense, in which case they will + * always be in the builddir). + * + * Note: as a general rule of automake, files that are generated only as + * part of the build-from-git process (but then are distributed with the + * tarball) always go in srcdir (even if doing a srcdir != builddir + * build from git) and are considered as distributed files. + * + * Since: 2.38 + */ + + +/** * GTestFixtureFunc: * @fixture: the test fixture * @user_data: the data provided when registering the test @@ -1790,6 +1816,19 @@ /** + * GTestSubprocessFlags: + * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child process will inherit the parent's stdin. Otherwise, the child's stdin is redirected to <filename>/dev/null</filename>. + * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child process will inherit the parent's stdout. Otherwise, the child's stdout will not be visible, but it will be captured to allow later tests with g_test_trap_assert_stdout(). + * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child process will inherit the parent's stderr. Otherwise, the child's stderr will not be visible, but it will be captured to allow later tests with g_test_trap_assert_stderr(). + * + * Flags to pass to g_test_trap_subprocess() to control input and output. + * + * Note that in contrast with g_test_trap_fork(), the default is to + * not show stdout and stderr. + */ + + +/** * GTestSuite: * * An opaque structure representing a test suite. @@ -1800,10 +1839,12 @@ * GTestTrapFlags: * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to <filename>/dev/null</filename> so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stdout(). * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to <filename>/dev/null</filename> so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stderr(). - * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked child process is shared with stdin of its parent process. It is redirected to <filename>/dev/null</filename> otherwise. + * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the child process is shared with stdin of its parent process. It is redirected to <filename>/dev/null</filename> otherwise. * * Test traps are guards around forked tests. * These flags determine what traps to set. + * + * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), which is deprecated. g_test_trap_subprocess() uses #GTestTrapSubprocessFlags. */ @@ -1898,7 +1939,7 @@ /** * GTimeZone: * - * #GDateTime is an opaque structure whose members cannot be accessed + * #GTimeZone is an opaque structure whose members cannot be accessed * directly. * * Since: 2.26 @@ -2877,7 +2918,7 @@ * format function the same as they would have been for the unmodified * string). * - * Place the attribute after the function declaration, just after the + * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. @@ -6434,50 +6475,14 @@ * * To destroy a #GHashTable use g_hash_table_destroy(). * - * <example> - * <title>Using a GHashTable as a set</title> - * <para> - * A common use-case for hash tables is to store information about - * a set of keys, without associating any particular value with each + * A common use-case for hash tables is to store information about a + * set of keys, without associating any particular value with each * key. GHashTable optimizes one way of doing so: If you store only * key-value pairs where key == value, then GHashTable does not * allocate memory to store the values, which can be a considerable - * space saving, if your set is large. - * </para> - * <programlisting> - * GHashTable * - * set_new (GHashFunc hash_func, - * GEqualFunc equal_func, - * GDestroyNotify destroy) - * { - * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL); - * } - * - * void - * set_add (GHashTable *set, - * gpointer element) - * { - * g_hash_table_replace (set, element, element); - * } - * - * gboolean - * set_contains (GHashTable *set, - * gpointer element) - * { - * return g_hash_table_lookup_extended (set, element, NULL, NULL); - * } - * - * gboolean - * set_remove (GHashTable *set, - * gpointer element) - * { - * return g_hash_table_remove (set, element); - * } - * </programlisting> - * </example> - * - * As of version 2.32, there is also a g_hash_table_add() function to - * add a key to a #GHashTable that is being used as a set. + * space saving, if your set is large. The functions + * g_hash_table_add() and g_hash_table_contains() are designed to be + * used when using #GHashTable this way. */ @@ -6522,16 +6527,21 @@ * easy-to-use form. * * In order to use these macros in an application, you must include - * <filename>glib/gi18n.h</filename>. For use in a library, must include + * <filename>glib/gi18n.h</filename>. For use in a library, you must include * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining * the GETTEXT_PACKAGE macro suitably for your library: * |[ * #define GETTEXT_PACKAGE "gtk20" * #include <glib/gi18n-lib.h> * ]| - * Note that you also have to call setlocale() and textdomain() (as well as - * bindtextdomain() and bind_textdomain_codeset()) early on in your main() - * to make gettext() work. + * For an application, note that you also have to call bindtextdomain(), + * bind_textdomain_codeset(), textdomain() and setlocale() early on in your + * main() to make gettext() work. + * + * For a library, you only have to call bindtextdomain() and + * bind_textdomain_codeset() in your initialization function. If your library + * doesn't have an initialization function, you can call the functions before + * the first translated message. * * The gettext manual covers details of how to set up message extraction * with xgettext. @@ -7355,8 +7365,6 @@ * SECTION:shell * @title: Shell-related Utilities * @short_description: shell-like commandline handling - * - * */ @@ -7364,8 +7372,6 @@ * SECTION:spawn * @Short_description: process launching * @Title: Spawning Processes - * - * */ @@ -8715,11 +8721,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another floating point number * - * Debugging macro to terminate the application with a warning - * message if a floating point number comparison fails. + * Debugging macro to compare two floating point numbers. * * The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is - * the same as <literal>g_assert (n1 op n2)</literal>. The advantage + * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8733,8 +8738,7 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare to unsigned integers. * * This is a variant of g_assert_cmpuint() that displays the numbers * in hexadecimal notation in the message. @@ -8749,11 +8753,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another integer * - * Debugging macro to terminate the application with a warning - * message if an integer comparison fails. + * Debugging macro to compare two integers. * * The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is - * the same as <literal>g_assert (n1 op n2)</literal>. The advantage + * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8767,12 +8770,13 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * - * Debugging macro to terminate the application with a warning - * message if a string comparison fails. The strings are compared - * using g_strcmp0(). + * Debugging macro to compare two strings. If the comparison fails, + * an error message is logged and the application is either terminated + * or the testcase marked as failed. + * The strings are compared using g_strcmp0(). * * The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is - * the same as <literal>g_assert (g_strcmp0 (s1, s2) op 0)</literal>. + * the same as <literal>g_assert_true (g_strcmp0 (s1, s2) op 0)</literal>. * The advantage of this macro is that it can produce a message that * includes the actual values of @s1 and @s2. * @@ -8790,11 +8794,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare two unsigned integers. * * The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is - * the same as <literal>g_assert (n1 op n2)</literal>. The advantage + * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8808,11 +8811,11 @@ * @dom: the expected error domain (a #GQuark) * @c: the expected error code * - * Debugging macro to terminate the application with a warning - * message if a method has not returned the correct #GError. + * Debugging macro to check that a method has returned + * the correct #GError. * * The effect of <literal>g_assert_error (err, dom, c)</literal> is - * the same as <literal>g_assert (err != NULL && err->domain + * the same as <literal>g_assert_true (err != NULL && err->domain * == dom && err->code == c)</literal>. The advantage of this * macro is that it can produce a message that includes the incorrect * error message and code. @@ -8826,14 +8829,29 @@ /** + * g_assert_false: + * @expr: the expression to check + * + * Debugging macro to check an expression is false. + * + * If the assertion fails (i.e. the expression is not false), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** * g_assert_no_error: * @err: a #GError, possibly %NULL * - * Debugging macro to terminate the application with a warning - * message if a method has returned a #GError. + * Debugging macro to check that a #GError is not set. * * The effect of <literal>g_assert_no_error (err)</literal> is - * the same as <literal>g_assert (err == NULL)</literal>. The advantage + * the same as <literal>g_assert_true (err == NULL)</literal>. The advantage * of this macro is that it can produce a message that includes * the error message and code. * @@ -8854,6 +8872,38 @@ /** + * g_assert_null: + * @expr: the expression to check + * + * Debugging macro to check an expression is %NULL. + * + * If the assertion fails (i.e. the expression is not %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** + * g_assert_true: + * @expr: the expression to check + * + * Debugging macro to check that an expression is true. + * + * If the assertion fails (i.e. the expression is not true), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** * g_async_queue_length: * @queue: a #GAsyncQueue. * @@ -9557,7 +9607,9 @@ * @text: zero-terminated string with base64 text to decode * @out_len: (out): The length of the decoded data is written here * - * Decode a sequence of Base-64 encoded text into binary data + * Decode a sequence of Base-64 encoded text into binary data. Note + * that the returned binary data is not necessarily zero-terminated, + * so it should not be used as a character string. * * Returns: (transfer full) (array length=out_len) (element-type guint8): newly allocated buffer containing the binary data that @text represents. The returned buffer must be freed with g_free(). * Since: 2.12 @@ -9860,9 +9912,9 @@ * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: an application's name - * @exec: (allow-none): location for the command line of the application, or %NULL - * @count: (allow-none): return location for the registration count, or %NULL - * @stamp: (allow-none): return location for the last registration time, or %NULL + * @exec: (allow-none) (out): return location for the command line of the application, or %NULL + * @count: (allow-none) (out): return location for the registration count, or %NULL + * @stamp: (allow-none) (out): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * * Gets the registration informations of @app_name for the bookmark for @@ -9888,7 +9940,7 @@ * g_bookmark_file_get_applications: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location of the length of the returned list, or %NULL + * @length: (allow-none) (out): return location of the length of the returned list, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the names of the applications that have registered the @@ -9897,7 +9949,7 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. * Since: 2.12 */ @@ -9922,7 +9974,7 @@ * g_bookmark_file_get_groups: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the list of group names of the bookmark for @uri. @@ -9933,7 +9985,7 @@ * The returned array is %NULL terminated, so @length may optionally * be %NULL. * - * Returns: a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. * Since: 2.12 */ @@ -9942,8 +9994,8 @@ * g_bookmark_file_get_icon: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @href: (allow-none): return location for the icon's location or %NULL - * @mime_type: (allow-none): return location for the icon's MIME type or %NULL + * @href: (allow-none) (out): return location for the icon's location or %NULL + * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL * @error: return location for a #GError or %NULL * * Gets the icon of the bookmark for @uri. @@ -10040,13 +10092,13 @@ /** * g_bookmark_file_get_uris: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the number of returned URIs, or %NULL + * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL * * Returns all URIs of the bookmarks in the bookmark file @bookmark. * The array of returned URIs will be %NULL-terminated, so @length may * optionally be %NULL. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. * Since: 2.12 */ @@ -10445,7 +10497,7 @@ /** * g_bookmark_file_to_data: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @bookmark as a string. @@ -11010,7 +11062,7 @@ /** - * g_checksum_get_digest: + * g_checksum_get_digest: (skip) * @checksum: a #GChecksum * @buffer: output buffer * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. @@ -11059,7 +11111,7 @@ * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * - * Returns: the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. + * Returns: (transfer full): the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ @@ -11088,7 +11140,7 @@ /** * g_checksum_update: * @checksum: a #GChecksum - * @data: buffer used to compute the checksum + * @data: (array length=length) (element-type guint8): buffer used to compute the checksum * @length: size of the buffer, or -1 if it is a null-terminated string. * * Feeds @data into an existing #GChecksum. The checksum must still be @@ -11186,9 +11238,9 @@ * g_spawn_close_pid() in the callback function for the source. * * Note further that using g_child_watch_source_new() is not - * compatible with calling <literal>waitpid(-1)</literal> in - * the application. Calling waitpid() for individual pids will - * still work fine. + * compatible with calling <literal>waitpid</literal> with a + * nonpositive first argument in the application. Calling waitpid() + * for individual pids will still work fine. * * Returns: the newly-created child watch source * Since: 2.4 @@ -11249,6 +11301,21 @@ /** + * g_close: + * @fd: A file descriptor + * @error: a #GError + * + * This wraps the close() call; in case of error, %errno will be + * preserved, but the error will also be stored as a #GError in @error. + * + * Besides using #GError, there is another major reason to prefer this + * function over the call provided by the system; on Unix, it will + * attempt to correctly handle %EINTR, which has platform-specific + * semantics. + */ + + +/** * g_compute_checksum_for_bytes: * @checksum_type: a #GChecksumType * @data: binary blob to compute the digest of @@ -11267,7 +11334,7 @@ /** * g_compute_checksum_for_data: * @checksum_type: a #GChecksumType - * @data: binary blob to compute the digest of + * @data: (array length=length) (element-type guint8): binary blob to compute the digest of * @length: length of @data * * Computes the checksum for a binary @data of @length. This is a @@ -11396,6 +11463,8 @@ * @mutex: a #GMutex that is currently locked * * Atomically releases @mutex and waits until @cond is signalled. + * When this function returns, @mutex is locked again and owned by the + * calling thread. * * When using condition variables, it is possible that a spurious wakeup * may occur (ie: g_cond_wait() returns even though g_cond_signal() was @@ -12605,7 +12674,7 @@ * * Calculates the difference in time between @end and @begin. The * #GTimeSpan that is returned is effectively @end - @begin (ie: - * positive if the first simparameter is larger). + * positive if the first parameter is larger). * * Returns: the difference between the two #GDateTime, as a time span expressed in microseconds. * Since: 2.26 @@ -14551,31 +14620,31 @@ /** * g_get_home_dir: * - * Gets the current user's home directory as defined in the - * password database. + * Gets the current user's home directory. * - * Note that in contrast to traditional UNIX tools, this function - * prefers <filename>passwd</filename> entries over the <envar>HOME</envar> - * environment variable. + * As with most UNIX tools, this function will return the value of the + * <envar>HOME</envar> environment variable if it is set to an existing + * absolute path name, falling back to the <filename>passwd</filename> + * file in the case that it is unset. * - * One of the reasons for this decision is that applications in many - * cases need special handling to deal with the case where - * <envar>HOME</envar> is - * <simplelist> - * <member>Not owned by the user</member> - * <member>Not writeable</member> - * <member>Not even readable</member> - * </simplelist> - * Since applications are in general <emphasis>not</emphasis> written - * to deal with these situations it was considered better to make - * g_get_home_dir() not pay attention to <envar>HOME</envar> and to - * return the real home directory for the user. If applications - * want to pay attention to <envar>HOME</envar>, they can do: - * |[ - * const char *homedir = g_getenv ("HOME"); - * if (!homedir) - * homedir = g_get_home_dir (<!-- -->); - * ]| + * If the path given in <envar>HOME</envar> is non-absolute, does not + * exist, or is not a directory, the result is undefined. + * + * <note><para> + * Before version 2.36 this function would ignore the + * <envar>HOME</envar> environment variable, taking the value from the + * <filename>passwd</filename> database instead. This was changed to + * increase the compatibility of GLib with other programs (and the XDG + * basedir specification) and to increase testability of programs + * based on GLib (by making it easier to run them from test + * frameworks). + * </para><para> + * If your program has a strong requirement for either the new or the + * old behaviour (and if you don't wish to increase your GLib + * dependency to ensure that the new behaviour is in effect) then you + * should either directly check the <envar>HOME</envar> environment + * variable yourself or unset it before calling any functions in GLib. + * </para></note> * * Returns: the current user's home directory */ @@ -14668,6 +14737,19 @@ /** + * g_get_num_processors: + * + * Determine the approximate number of threads that the system will + * schedule simultaneously for this process. This is intended to be + * used as a parameter to g_thread_pool_new() for CPU bound tasks and + * similar cases. + * + * Returns: Number of schedulable threads, always greater than 0 + * Since: 2.36 + */ + + +/** * g_get_prgname: * * Gets the name of the program. This name should <emphasis>not</emphasis> @@ -14775,12 +14857,19 @@ /** * g_get_tmp_dir: * - * Gets the directory to use for temporary files. This is found from - * inspecting the environment variables <envar>TMPDIR</envar>, - * <envar>TMP</envar>, and <envar>TEMP</envar> in that order. If none - * of those are defined "/tmp" is returned on UNIX and "C:\" on Windows. - * The encoding of the returned string is system-defined. On Windows, - * it is always UTF-8. The return value is never %NULL or the empty string. + * Gets the directory to use for temporary files. + * + * On UNIX, this is taken from the <envar>TMPDIR</envar> environment + * variable. If the variable is not set, <literal>P_tmpdir</literal> is + * used, as defined by the system C library. Failing that, a hard-coded + * default of "/tmp" is returned. + * + * On Windows, the <envar>TEMP</envar> environment variable is used, + * with the root directory of the Windows installation (eg: "C:\") used + * as a default. + * + * The encoding of the returned string is system-defined. On Windows, it + * is always UTF-8. The return value is never %NULL or the empty string. * * Returns: the directory to use for temporary files. */ @@ -15054,8 +15143,8 @@ * g_hash_table_get_keys: * @hash_table: a #GHashTable * - * Retrieves every key inside @hash_table. The returned data - * is valid until @hash_table is modified. + * Retrieves every key inside @hash_table. The returned data is valid + * until changes to the hash release those keys. * * Returns: a #GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. * Since: 2.14 @@ -16119,8 +16208,6 @@ /** * g_io_channel_error_quark: * - * - * * Returns: the quark used as %G_IO_CHANNEL_ERROR */ @@ -16326,7 +16413,7 @@ /** * g_io_channel_read_unichar: * @channel: a #GIOChannel - * @thechar: a location to return a character + * @thechar: (out): a location to return a character * @error: a location to return an error of type #GConvertError or #GIOChannelError * * Reads a Unicode character from @channel. @@ -16930,7 +17017,7 @@ * returned array is %NULL-terminated, so @length may optionally * be %NULL. * - * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array or %NULL if the key isn't found. The string array should be freed with g_strfreev(). + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array or %NULL if the key isn't found. The string array should be freed with g_strfreev(). * Since: 2.6 */ @@ -16982,7 +17069,7 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a %NULL-terminated string array or %NULL if the specified key cannot be found. The array should be freed with g_strfreev(). + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a %NULL-terminated string array or %NULL if the specified key cannot be found. The array should be freed with g_strfreev(). * Since: 2.6 */ @@ -17352,7 +17439,7 @@ * @group_name: a group name * @key: a key * @locale: a locale identifier - * @list: (array length=length zero-terminated=1): a %NULL-terminated array of locale string values + * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values * @length: the length of @list * * Associates a list of string values for @key and @locale under @@ -17385,7 +17472,7 @@ * @key_file: a #GKeyFile * @group_name: a group name * @key: a key - * @list: (array length=length zero-terminated=1) (element-type utf8): an array of string values + * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values * @length: number of string values in @list * * Associates a list of string values for @key under @group_name. @@ -18182,7 +18269,7 @@ * * Adds a file descriptor to the set of file descriptors polled for * this context. This will very seldom be used directly. Instead - * a typical event source will use g_source_add_poll() instead. + * a typical event source will use g_source_add_unix_fd() instead. */ @@ -18560,8 +18647,34 @@ * g_main_context_wakeup: * @context: a #GMainContext * - * If @context is currently waiting in a poll(), interrupt - * the poll(), and continue the iteration process. + * If @context is currently blocking in g_main_context_iteration() + * waiting for a source to become ready, cause it to stop blocking + * and return. Otherwise, cause the next invocation of + * g_main_context_iteration() to return without blocking. + * + * This API is useful for low-level control over #GMainContext; for + * example, integrating it with main loop implementations such as + * #GMainLoop. + * + * Another related use for this function is when implementing a main + * loop with a termination condition, computed from multiple threads: + * + * |[ + * #define NUM_TASKS 10 + * static volatile gint tasks_remaining = NUM_TASKS; + * ... + * + * while (g_atomic_int_get (&tasks_remaining) != 0) + * g_main_context_iteration (NULL, TRUE); + * ]| + * + * Then in a thread: + * |[ + * perform_work(); + * + * if (g_atomic_int_dec_and_test (&tasks_remaining)) + * g_main_context_wakeup (NULL); + * ]| */ @@ -19292,6 +19405,28 @@ /** + * g_markup_parse_context_ref: + * @context: a #GMarkupParseContext + * + * Increases the reference count of @context. + * + * Returns: the same @context + * Since: 2.36 + */ + + +/** + * g_markup_parse_context_unref: + * @context: a #GMarkupParseContext + * + * Decreases the reference count of @context. When its reference count + * drops to 0, it is freed. + * + * Since: 2.36 + */ + + +/** * g_markup_printf_escaped: * @format: printf() style format string * @...: the arguments to insert in the format string @@ -19566,19 +19701,11 @@ * stops at the partial match. * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD * are set, the latter takes precedence. - * See <ulink>man:pcrepartial</ulink> for more information on partial matching. * - * Because of the way certain internal optimizations are implemented - * the partial matching algorithm cannot be used with all patterns. - * So repeated single characters such as "a{2,4}" and repeated single - * meta-sequences such as "\d+" are not permitted if the maximum number - * of occurrences is greater than one. Optional items such as "\d?" - * (where the maximum is one) are permitted. Quantifiers with any values - * are permitted after parentheses, so the invalid examples above can be - * coded thus "(a){2,4}" and "(\d)+". If #G_REGEX_MATCH_PARTIAL or - * #G_REGEX_MATCH_PARTIAL_HARD is set - * for a pattern that does not conform to the restrictions, matching - * functions return an error. + * There were formerly some restrictions on the pattern for partial matching. + * The restrictions no longer apply. + * + * See <ulink>man:pcrepartial</ulink> for more information on partial matching. * * Returns: %TRUE if the match was partial, %FALSE otherwise * Since: 2.14 @@ -20556,7 +20683,7 @@ /** * g_option_context_new: - * @parameter_string: a string which is displayed in the first line of <option>--help</option> output, after the usage summary <literal><replaceable>programname</replaceable> [OPTION...]</literal> + * @parameter_string: (allow-none): a string which is displayed in the first line of <option>--help</option> output, after the usage summary <literal><replaceable>programname</replaceable> [OPTION...]</literal> * * Creates a new option context. * @@ -22480,6 +22607,19 @@ /** + * g_regex_get_max_lookbehind: + * @regex: a #GRegex structure + * + * Gets the number of characters in the longest lookbehind assertion in the + * pattern. This information is useful when doing multi-segment matching using + * the partial matching facilities. + * + * Returns: the number of characters in the longest lookbehind assertion. + * Since: 2.38 + */ + + +/** * g_regex_get_pattern: * @regex: a #GRegex structure * @@ -23815,7 +23955,7 @@ * doing unsorted insertions. * </para></note> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. + * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists. * Since: 2.28 */ @@ -23843,7 +23983,7 @@ * doing unsorted insertions. * </para></note> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. + * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists. * Since: 2.28 */ @@ -25001,6 +25141,32 @@ * event source. The event source's check function will typically test * the @revents field in the #GPollFD struct and return %TRUE if events need * to be processed. + * + * Using this API forces the linear scanning of event sources on each + * main loop iteration. Newly-written event sources should try to use + * g_source_add_unix_fd() instead of this API. + */ + + +/** + * g_source_add_unix_fd: + * @source: a #GSource + * @fd: the fd to monitor + * @events: an event mask + * + * Monitors @fd for the IO events in @events. + * + * The tag returned by this function can be used to remove or modify the + * monitoring of the fd using g_source_remove_unix_fd() or + * g_source_modify_unix_fd(). + * + * It is not necessary to remove the fd before destroying the source; it + * will be cleaned up automatically. + * + * As the name suggests, this function is not available on Windows. + * + * Returns: an opaque tag + * Since: 2.36 */ @@ -25103,6 +25269,20 @@ /** + * g_source_get_ready_time: + * @source: a #GSource + * + * Gets the "ready time" of @source, as set by + * g_source_set_ready_time(). + * + * Any time before the current monotonic time (including 0) is an + * indication that the source will fire immediately. + * + * Returns: the monotonic ready time, -1 for "never" + */ + + +/** * g_source_get_time: * @source: a #GSource * @@ -25190,6 +25370,25 @@ /** + * g_source_modify_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * @new_events: the new event mask to watch + * + * Updates the event mask to watch for the fd identified by @tag. + * + * @tag is the tag returned from g_source_add_unix_fd(). + * + * If you want to remove a fd, don't set its event mask to zero. + * Instead, call g_source_remove_unix_fd(). + * + * As the name suggests, this function is not available on Windows. + * + * Since: 2.36 + */ + + +/** * g_source_new: * @source_funcs: structure containing functions that implement the sources behavior. * @struct_size: size of the #GSource structure to create. @@ -25208,6 +25407,24 @@ /** + * g_source_query_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * + * Queries the events reported for the fd corresponding to @tag on + * @source during the last poll. + * + * The return value of this function is only defined when the function + * is called from the check or dispatch functions for @source. + * + * As the name suggests, this function is not available on Windows. + * + * Returns: the conditions reported on the fd + * Since: 2.36 + */ + + +/** * g_source_ref: * @source: a #GSource * @@ -25282,6 +25499,23 @@ /** + * g_source_remove_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * + * Reverses the effect of a previous call to g_source_add_unix_fd(). + * + * You only need to call this if you want to remove an fd from being + * watched while keeping the same source around. In the normal case you + * will just want to destroy the source. + * + * As the name suggests, this function is not available on Windows. + * + * Since: 2.36 + */ + + +/** * g_source_set_callback: * @source: the source * @func: a callback function @@ -25387,6 +25621,32 @@ /** + * g_source_set_ready_time: + * @source: a #GSource + * @ready_time: the monotonic time at which the source will be ready, 0 for "immediately", -1 for "never" + * + * Sets a #GSource to be dispatched when the given monotonic time is + * reached (or passed). If the monotonic time is in the past (as it + * always will be if @ready_time is 0) then the source will be + * dispatched immediately. + * + * If @ready_time is -1 then the source is never woken up on the basis + * of the passage of time. + * + * Dispatching the source does not reset the ready time. You should do + * so yourself, from the source dispatch function. + * + * Note that if you have a pair of sources where the ready time of one + * suggests that it will be delivered first but the priority for the + * other suggests that it would be delivered first, and the ready time + * for both sources is reached during the same main context iteration + * then the order of dispatch is undefined. + * + * Since: 2.36 + */ + + +/** * g_source_unref: * @source: a #GSource * @@ -25760,7 +26020,7 @@ * passing %NULL for @standard_output and @standard_error. * * If @exit_status is non-%NULL, the platform-specific exit status of - * the child is stored there; see the doucumentation of + * the child is stored there; see the documentation of * g_spawn_check_exit_status() for how to use and interpret this. * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in * @flags. @@ -26818,7 +27078,7 @@ * characters of the strings. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. - * Deprecated: 2.2: The problem with g_strncasecmp() is that it does the comparison by calling toupper()/tolower(). These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an I18N standpoint by operating on bytes, since characters may be multibyte. Thus g_strncasecmp() is broken if your string is guaranteed to be ASCII, since it's locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement functions: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8. + * Deprecated: 2.2: The problem with g_strncasecmp() is that it does the comparison by calling toupper()/tolower(). These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an I18N standpoint by operating on bytes, since characters may be multibyte. Thus g_strncasecmp() is broken if your string is guaranteed to be ASCII, since it's locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement techniques: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold() followed by strcmp() on the resulting strings, which is good for case-insensitive sorting of UTF-8. */ @@ -27064,6 +27324,11 @@ * slash-separated portions of @testpath. The @test_data argument * will be passed as first argument to @test_func. * + * If @testpath includes the component "subprocess" anywhere in it, + * the test will be skipped by default, and only run if explicitly + * required via the <option>-p</option> command-line option or + * g_test_trap_subprocess(). + * * Since: 2.16 */ @@ -27092,6 +27357,11 @@ * created on the fly and added to the root fixture, based on the * slash-separated portions of @testpath. * + * If @testpath includes the component "subprocess" anywhere in it, + * the test will be skipped by default, and only run if explicitly + * required via the <option>-p</option> command-line option or + * g_test_trap_subprocess(). + * * Since: 2.16 */ @@ -27140,6 +27410,40 @@ /** + * g_test_build_filename: + * @file_type: the type of file (built vs. distributed) + * @first_path: the first segment of the pathname + * @...: %NULL-terminated additional path segments + * + * Creates the pathname to a data file that is required for a test. + * + * This function is conceptually similar to g_build_filename() except + * that the first argument has been replaced with a #GTestFileType + * argument. + * + * The data file should either have been distributed with the module + * containing the test (%G_TEST_DIST) or built as part of the build + * system of that module (%G_TEST_BUILT). + * + * In order for this function to work in srcdir != builddir situations, + * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to + * have been defined. As of 2.38, this is done by the Makefile.decl + * included in GLib. Please ensure that your copy is up to date before + * using this function. + * + * In case neither variable is set, this function will fall back to + * using the dirname portion of argv[0], possibly removing ".libs". + * This allows for casual running of tests directly from the commandline + * in the srcdir == builddir case and should also support running of + * installed tests, assuming the data files have been installed in the + * same relative path as the test binary. + * + * Returns: the path of the file, to be freed using g_free() + * Since: 2.38 + */ + + +/** * g_test_create_case: * @test_name: the name for the test case * @data_size: the size of the fixture data structure @@ -27204,15 +27508,15 @@ * * context is already owned by another thread. * */ * g_test_expect_message (G_LOG_DOMAIN, - * G_LOG_LEVEL_CRITICIAL, - * "assertion.*acquired_context.*failed"); + * G_LOG_LEVEL_CRITICAL, + * "assertion*acquired_context*failed"); * g_main_context_push_thread_default (bad_context); * g_test_assert_expected_messages (); * ]| * * Note that you cannot use this to test g_error() messages, since * g_error() intentionally never returns even if the program doesn't - * abort; use g_test_trap_fork() in this case. + * abort; use g_test_trap_subprocess() in this case. * * Since: 2.34 */ @@ -27240,6 +27544,64 @@ /** + * g_test_failed: + * + * Returns whether a test has already failed. This will + * be the case when g_test_fail(), g_test_incomplete() + * or g_test_skip() have been called, but also if an + * assertion has failed. + * + * This can be useful to return early from a test if + * continuing after a failed assertion might be harmful. + * + * The return value of this function is only meaningful + * if it is called from inside a test function. + * + * Returns: %TRUE if the test has failed + * Since: 2.38 + */ + + +/** + * g_test_get_dir: + * @file_type: the type of file (built vs. distributed) + * + * Gets the pathname of the directory containing test files of the type + * specified by @file_type. + * + * This is approximately the same as calling g_test_build_filename("."), + * but you don't need to free the return value. + * + * Returns: the path of the directory, owned by GLib + * Since: 2.38 + */ + + +/** + * g_test_get_filename: + * @file_type: the type of file (built vs. distributed) + * @first_path: the first segment of the pathname + * @...: %NULL-terminated additional path segments + * + * Gets the pathname to a data file that is required for a test. + * + * This is the same as g_test_build_filename() with two differences. + * The first difference is that must only use this function from within + * a testcase function. The second difference is that you need not free + * the return value -- it will be automatically freed when the testcase + * finishes running. + * + * It is safe to use this function from a thread inside of a testcase + * but you must ensure that all such uses occur before the main testcase + * function returns (ie: it is best to ensure that all threads have been + * joined). + * + * Returns: the path, automatically freed at the end of the testcase + * Since: 2.38 + */ + + +/** * g_test_get_root: * * Get the toplevel test suite for the test path API. @@ -27250,6 +27612,25 @@ /** + * g_test_incomplete: + * @msg: (allow-none): explanation + * + * Indicates that a test failed because of some incomplete + * functionality. This function can be called multiple times + * from the same test. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + +/** * g_test_init: * @argc: Address of the @argc parameter of the main() function. Changed if any arguments were handled. * @argv: Address of the @argv parameter of main(). Any parameters understood by g_test_init() stripped before return. @@ -27284,6 +27665,8 @@ * <term><option>-p <replaceable>TESTPATH</replaceable></option></term> * <listitem><para> * Execute all tests matching <replaceable>TESTPATH</replaceable>. + * This can also be used to force a test to run that would otherwise + * be skipped (ie, a test whose name contains "/subprocess"). * </para></listitem> * </varlistentry> * <varlistentry> @@ -27314,8 +27697,8 @@ * <term>undefined</term> * <listitem><para> * Tests for undefined behaviour, may provoke programming errors - * under g_test_trap_fork() to check that appropriate assertions - * or warnings are given + * under g_test_trap_subprocess() or g_test_expect_messages() to check + * that appropriate assertions or warnings are given * </para></listitem> * </varlistentry> * <varlistentry> @@ -27338,6 +27721,16 @@ /** + * g_test_initialized: + * + * Returns %TRUE if g_test_init() has been called. + * + * Returns: %TRUE if g_test_init() has been called. + * Since: 2.36 + */ + + +/** * g_test_log_buffer_free: * * Internal function for gtester to free test log messages, no ABI guarantees provided. @@ -27608,6 +28001,42 @@ /** + * g_test_set_nonfatal_assertions: + * + * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), + * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), + * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), + * g_assert_error(), g_test_assert_expected_messages() and the various + * g_test_trap_assert_*() macros to not abort to program, but instead + * call g_test_fail() and continue. + * + * Note that the g_assert_not_reached() and g_assert() are not + * affected by this. + * + * This function can only be called after g_test_init(). + * + * Since: 2.38 + */ + + +/** + * g_test_skip: + * @msg: (allow-none): explanation + * + * Indicates that a test was skipped. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + +/** * g_test_slow: * * Returns %TRUE if tests are run in slow mode. @@ -27619,6 +28048,17 @@ /** + * g_test_subprocess: + * + * Returns %TRUE (after g_test_init() has been called) if the test + * program is running under g_test_trap_subprocess(). + * + * Returns: %TRUE if the test program is running under g_test_trap_subprocess(). + * Since: 2.38 + */ + + +/** * g_test_suite_add: * @suite: a #GTestSuite * @test_case: a #GTestCase @@ -27683,13 +28123,13 @@ /** * g_test_trap_assert_failed: * - * Assert that the last forked test failed. - * See g_test_trap_fork(). + * Assert that the last test subprocess failed. + * See g_test_trap_subprocess(). * * This is sometimes used to test situations that are formally considered to * be undefined behaviour, like inputs that fail a g_return_if_fail() * check. In these situations you should skip the entire test, including the - * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE + * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE * to indicate that undefined behaviour may be tested. * * Since: 2.16 @@ -27699,8 +28139,8 @@ /** * g_test_trap_assert_passed: * - * Assert that the last forked test passed. - * See g_test_trap_fork(). + * Assert that the last test subprocess passed. + * See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27710,14 +28150,15 @@ * g_test_trap_assert_stderr: * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> * - * Assert that the stderr output of the last forked test - * matches @serrpattern. See g_test_trap_fork(). + * Assert that the stderr output of the last test subprocess + * matches @serrpattern. See g_test_trap_subprocess(). * - * This is sometimes used to test situations that are formally considered to - * be undefined behaviour, like inputs that fail a g_return_if_fail() - * check. In these situations you should skip the entire test, including the - * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE - * to indicate that undefined behaviour may be tested. + * This is sometimes used to test situations that are formally + * considered to be undefined behaviour, like code that hits a + * g_assert() or g_error(). In these situations you should skip the + * entire test, including the call to g_test_trap_subprocess(), unless + * g_test_undefined() returns %TRUE to indicate that undefined + * behaviour may be tested. * * Since: 2.16 */ @@ -27727,8 +28168,8 @@ * g_test_trap_assert_stderr_unmatched: * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> * - * Assert that the stderr output of the last forked test - * does not match @serrpattern. See g_test_trap_fork(). + * Assert that the stderr output of the last test subprocess + * does not match @serrpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27738,8 +28179,8 @@ * g_test_trap_assert_stdout: * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> * - * Assert that the stdout output of the last forked test matches - * @soutpattern. See g_test_trap_fork(). + * Assert that the stdout output of the last test subprocess matches + * @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27749,8 +28190,8 @@ * g_test_trap_assert_stdout_unmatched: * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> * - * Assert that the stdout output of the last forked test - * does not match @soutpattern. See g_test_trap_fork(). + * Assert that the stdout output of the last test subprocess + * does not match @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27762,8 +28203,10 @@ * @test_trap_flags: Flags to modify forking behaviour. * * Fork the current test program to execute a test case that might - * not return or that might abort. The forked test case is aborted - * and considered failing if its run time exceeds @usec_timeout. + * not return or that might abort. + * + * If @usec_timeout is non-0, the forked test case is aborted and + * considered failing if its run time exceeds it. * * The forking behavior can be configured with the #GTestTrapFlags flags. * @@ -27782,25 +28225,24 @@ * g_printerr ("some stderr text: semagic43\n"); * exit (0); /* successful test run */ * } - * g_test_trap_assert_passed(); + * g_test_trap_assert_passed (); * g_test_trap_assert_stdout ("*somagic17*"); * g_test_trap_assert_stderr ("*semagic43*"); * } * ]| * - * This function is implemented only on Unix platforms. - * * Returns: %TRUE for the forked child and %FALSE for the executing parent process. * Since: 2.16 + * Deprecated: This function is implemented only on Unix platforms, and is not always reliable due to problems inherent in fork-without-exec. Use g_test_trap_subprocess() instead. */ /** * g_test_trap_has_passed: * - * Check the result of the last g_test_trap_fork() call. + * Check the result of the last g_test_trap_subprocess() call. * - * Returns: %TRUE if the last forked child terminated successfully. + * Returns: %TRUE if the last test subprocess terminated successfully. * Since: 2.16 */ @@ -27808,20 +28250,91 @@ /** * g_test_trap_reached_timeout: * - * Check the result of the last g_test_trap_fork() call. + * Check the result of the last g_test_trap_subprocess() call. * - * Returns: %TRUE if the last forked child got killed due to a fork timeout. + * Returns: %TRUE if the last test subprocess got killed due to a timeout. * Since: 2.16 */ /** + * g_test_trap_subprocess: + * @test_path: Test to run in a subprocess + * @usec_timeout: Timeout for the subprocess test in micro seconds. + * @test_flags: Flags to modify subprocess behaviour. + * + * Respawns the test program to run only @test_path in a subprocess. + * This can be used for a test case that might not return, or that + * might abort. @test_path will normally be the name of the parent + * test, followed by "<literal>/subprocess/</literal>" and then a name + * for the specific subtest (or just ending with + * "<literal>/subprocess</literal>" if the test only has one child + * test); tests with names of this form will automatically be skipped + * in the parent process. + * + * If @usec_timeout is non-0, the test subprocess is aborted and + * considered failing if its run time exceeds it. + * + * The subprocess behavior can be configured with the + * #GTestSubprocessFlags flags. + * + * You can use methods such as g_test_trap_assert_passed(), + * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to + * check the results of the subprocess. (But note that + * g_test_trap_assert_stdout() and g_test_trap_assert_stderr() + * cannot be used if @test_flags specifies that the child should + * inherit the parent stdout/stderr.) + * + * If your <literal>main ()</literal> needs to behave differently in + * the subprocess, you can call g_test_subprocess() (after calling + * g_test_init()) to see whether you are in a subprocess. + * + * The following example tests that calling + * <literal>my_object_new(1000000)</literal> will abort with an error + * message. + * + * |[ + * static void + * test_create_large_object_subprocess (void) + * { + * my_object_new (1000000); + * } + * + * static void + * test_create_large_object (void) + * { + * g_test_trap_subprocess ("/myobject/create_large_object/subprocess", 0, 0); + * g_test_trap_assert_failed (); + * g_test_trap_assert_stderr ("*ERROR*too large*"); + * } + * + * int + * main (int argc, char **argv) + * { + * g_test_init (&argc, &argv, NULL); + * + * g_test_add_func ("/myobject/create_large_object", + * test_create_large_object); + * /* Because of the '/subprocess' in the name, this test will + * * not be run by the g_test_run () call below. + * */ + * g_test_add_func ("/myobject/create_large_object/subprocess", + * test_create_large_object_subprocess); + * + * return g_test_run (); + * } + * ]| + * + * Since: 2.38 + */ + + +/** * g_test_undefined: * * Returns %TRUE if tests may provoke assertions and other formally-undefined - * behaviour under g_test_trap_fork(), to verify that appropriate warnings - * are given. It can be useful to turn this off if running tests under - * valgrind. + * behaviour, to verify that appropriate warnings are given. It might, in some + * cases, be useful to turn this off if running tests under valgrind. * * Returns: %TRUE if tests may provoke programming errors */ @@ -27886,7 +28399,7 @@ /** * g_thread_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @@ -27897,6 +28410,7 @@ * with g_thread_join(). * * The @name can be useful for discriminating threads in a debugger. + * It is not used for other purposes and does not have to be unique. * Some systems restrict the length of @name to 16 bytes. * * If the thread can not be created the program aborts. See @@ -28189,7 +28703,7 @@ /** * g_thread_try_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @error: return location for error, or %NULL @@ -28403,20 +28917,50 @@ * something that would pass as a valid value for the * <varname>TZ</varname> environment variable (including %NULL). * + * In Windows, @identifier can also be the unlocalized name of a time + * zone for standard time, for example "Pacific Standard Time". + * * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or * <literal>"±hh:mm"</literal>. ISO 8601 additionally specifies - * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>. - * - * The <varname>TZ</varname> environment variable typically corresponds - * to the name of a file in the zoneinfo database, but there are many - * other possibilities. Note that those other possibilities are not - * currently implemented, but are planned. + * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>. Offsets are + * time values to be added to Coordinated Universal Time (UTC) to get + * the local time. + * + * In Unix, the <varname>TZ</varname> environment variable typically + * corresponds to the name of a file in the zoneinfo database, or + * string in "std offset [dst [offset],start[/time],end[/time]]" + * (POSIX) format. There are no spaces in the specification. The + * name of standard and daylight savings time zone must be three or more + * alphabetic characters. Offsets are time values to be added to local + * time to get Coordinated Universal Time (UTC) and should be + * <literal>"[±]hh[[:]mm[:ss]]"</literal>. Dates are either + * <literal>"Jn"</literal> (Julian day with n between 1 and 365, leap + * years not counted), <literal>"n"</literal> (zero-based Julian day + * with n between 0 and 365) or <literal>"Mm.w.d"</literal> (day d + * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day + * 0 is a Sunday). Times are in local wall clock time, the default is + * 02:00:00. + * + * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also + * accepts POSIX format. The Windows format uses US rules for all time + * zones; daylight savings time is 60 minutes behind the standard time + * with date and time of change taken from Pacific Standard Time. + * Offsets are time values to be added to the local time to get + * Coordinated Universal Time (UTC). * * g_time_zone_new_local() calls this function with the value of the * <varname>TZ</varname> environment variable. This function itself is * independent of the value of <varname>TZ</varname>, but if @identifier * is %NULL then <filename>/etc/localtime</filename> will be consulted - * to discover the correct timezone. + * to discover the correct time zone on Unix and the registry will be + * consulted or GetTimeZoneInformation() will be used to get the local + * time zone on Windows. + * + * If intervals are not available, only time zone rules from + * <varname>TZ</varname> environment variable or other means, then they + * will be computed from year 1900 to 2037. If the maximum year for the + * rules is available and it is greater than 2037, then it will followed + * instead. * * See <ulink * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339 @@ -28425,7 +28969,10 @@ * full list of valid time offsets. See <ulink * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The * GNU C Library manual</ulink> for an explanation of the possible - * values of the <varname>TZ</varname> environment variable. + * values of the <varname>TZ</varname> environment variable. See <ulink + * url='http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx'> + * Microsoft Time Zone Index Values</ulink> for the list of time zones + * on Windows. * * You should release the return value by calling g_time_zone_unref() * when you are done with it. @@ -29673,6 +30220,68 @@ /** + * g_unix_fd_add: + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * @function: a #GPollFDFunc + * @user_data: data to pass to @function + * + * Sets a function to be called when the IO condition, as specified by + * @condition becomes true for @fd. + * + * @function will be called when the specified IO condition becomes + * %TRUE. The function is expected to clear whatever event caused the + * IO condition to become true and return %TRUE in order to be notified + * when it happens again. If @function returns %FALSE then the watch + * will be cancelled. + * + * The return value of this function can be passed to g_source_remove() + * to cancel the watch at any time that it exists. + * + * The source will never close the fd -- you must do it yourself. + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.36 + */ + + +/** + * g_unix_fd_add_full: + * @priority: the priority of the source + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * @function: a #GUnixFDSourceFunc + * @user_data: data to pass to @function + * @notify: function to call when the idle is removed, or %NULL + * + * Sets a function to be called when the IO condition, as specified by + * @condition becomes true for @fd. + * + * This is the same as g_unix_fd_add(), except that it allows you to + * specify a non-default priority and a provide a #GDestroyNotify for + * @user_data. + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.36 + */ + + +/** + * g_unix_fd_source_new: + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * + * Creates a #GSource to watch for a particular IO condition on a file + * descriptor. + * + * The source will never close the fd -- you must do it yourself. + * + * Returns: the newly created #GSource + * Since: 2.36 + */ + + +/** * g_unix_open_pipe: * @fds: Array of two integers * @flags: Bitfield of file descriptor flags, see "man 2 fcntl" @@ -29737,6 +30346,7 @@ * using g_source_remove(). * * Returns: An ID (greater than 0) for the event source + * Rename to: g_unix_signal_add * Since: 2.30 */ @@ -29746,11 +30356,15 @@ * @signum: A signal number * * Create a #GSource that will be dispatched upon delivery of the UNIX - * signal @signum. Currently only <literal>SIGHUP</literal>, - * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can - * be monitored. Note that unlike the UNIX default, all sources which - * have created a watch will be dispatched, regardless of which - * underlying thread invoked g_unix_signal_source_new(). + * signal @signum. In GLib versions before 2.36, only + * <literal>SIGHUP</literal>, <literal>SIGINT</literal>, + * <literal>SIGTERM</literal> can be monitored. In GLib 2.36, + * <literal>SIGUSR1</literal> and <literal>SIGUSR2</literal> were + * added. + * + * Note that unlike the UNIX default, all sources which have created a + * watch will be dispatched, regardless of which underlying thread + * invoked g_unix_signal_source_new(). * * For example, an effective use of this function is to handle <literal>SIGTERM</literal> * cleanly; flushing any outstanding files, and then calling @@ -29821,7 +30435,7 @@ /** * g_uri_escape_string: * @unescaped: the unescaped input string. - * @reserved_chars_allowed: a string of reserved characters that are allowed to be used, or %NULL. + * @reserved_chars_allowed: (allow-none): a string of reserved characters that are allowed to be used, or %NULL. * @allow_utf8: %TRUE if the result can include UTF-8 characters. * * Escapes a string for use in a URI. @@ -29888,7 +30502,7 @@ /** * g_uri_unescape_string: * @escaped_string: an escaped string to be unescaped. - * @illegal_characters: an optional string of illegal characters not to be allowed. + * @illegal_characters: (allow-none): a string of illegal characters not to be allowed, or %NULL. * * Unescapes a whole escaped string. * @@ -30757,7 +31371,7 @@ * * The return value must be freed using g_free(). * - * Returns: (transfer full) (array length=length zero-terminated=1) (element-type guint8): a newly allocated string + * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): a newly allocated string * Since: 2.26 */ @@ -31038,6 +31652,20 @@ /** + * g_variant_get_data_as_bytes: + * @value: a #GVariant + * + * Returns a pointer to the serialised form of a #GVariant instance. + * The semantics of this function are exactly the same as + * g_variant_get_data(), except that the returned #GBytes holds + * a reference to the variant data. + * + * Returns: (transfer full): A new #GBytes representing the variant data + * Since: 2.36 + */ + + +/** * g_variant_get_double: * @value: a double #GVariant instance * @@ -32011,6 +32639,23 @@ /** + * g_variant_new_from_bytes: + * @type: a #GVariantType + * @bytes: a #GBytes + * @trusted: if the contents of @bytes are trusted + * + * Constructs a new serialised-mode #GVariant instance. This is the + * inner interface for creation of new serialised values that gets + * called from various functions in gvariant.c. + * + * A reference is taken on @bytes. + * + * Returns: (transfer none): a new #GVariant with a floating reference + * Since: 2.36 + */ + + +/** * g_variant_new_from_data: * @type: a definite #GVariantType * @data: (array length=size) (element-type guint8): the serialised data @@ -32213,6 +32858,22 @@ /** + * g_variant_new_printf: (skip) + * @format_string: a printf-style format string + * @...: arguments for @format_string + * + * Creates a string-type GVariant using printf formatting. + * + * This is similar to calling g_strdup_printf() and then + * g_variant_new_string() but it saves a temporary variable and an + * unnecessary copy. + * + * Returns: (transfer none): a floating reference to a new string #GVariant instance + * Since: 2.38 + */ + + +/** * g_variant_new_signature: * @signature: a normal C nul-terminated string * @@ -32254,6 +32915,26 @@ /** + * g_variant_new_take_string: (skip) + * @string: a normal utf8 nul-terminated string + * + * Creates a string #GVariant with the contents of @string. + * + * @string must be valid utf8. + * + * This function consumes @string. g_free() will be called on @string + * when it is no longer required. + * + * You must not modify or access @string in any other way after passing + * it to this function. It is even possible that @string is immediately + * freed. + * + * Returns: (transfer none): a floating reference to a new string #GVariant instance + * Since: 2.38 + */ + + +/** * g_variant_new_tuple: * @children: (array length=n_children): the items to make the tuple out of * @n_children: the length of @children |