Commit 41013a01 authored by Christoph Reiter's avatar Christoph Reiter 🐍 Committed by Christoph Reiter

glib: Add filename type annotations

Adds the filename annotation for all file names
and things which can contain file names like
environment variables, argv-

On Unix they can contain anything while on Windows
they are always utf-8.

https://bugzilla.gnome.org/show_bug.cgi?id=767245
parent 7d8e98ee
......@@ -1657,7 +1657,8 @@ g_bookmark_file_load_from_data (GBookmarkFile *bookmark,
/**
* g_bookmark_file_load_from_file:
* @bookmark: an empty #GBookmarkFile struct
* @filename: the path of a filename to load, in the GLib file name encoding
* @filename: (type filename): the path of a filename to load, in the
* GLib file name encoding
* @error: return location for a #GError, or %NULL
*
* Loads a desktop bookmark file into an empty #GBookmarkFile structure.
......@@ -1765,9 +1766,9 @@ find_file_in_data_dirs (const gchar *file,
/**
* g_bookmark_file_load_from_data_dirs:
* @bookmark: a #GBookmarkFile
* @file: a relative path to a filename to open and parse
* @full_path: (allow-none): return location for a string containing the full path
* of the file, or %NULL
* @file: (type filename): a relative path to a filename to open and parse
* @full_path: (type filename) (allow-none): return location for a string
* containing the full path of the file, or %NULL
* @error: return location for a #GError, or %NULL
*
* This function looks for a desktop bookmark file named @file in the
......@@ -1881,7 +1882,7 @@ g_bookmark_file_to_data (GBookmarkFile *bookmark,
/**
* g_bookmark_file_to_file:
* @bookmark: a #GBookmarkFile
* @filename: path of the output file
* @filename: (type filename): path of the output file
* @error: return location for a #GError, or %NULL
*
* This function outputs @bookmark into a file. The write process is
......
......@@ -1114,7 +1114,7 @@ get_filename_charset (const gchar **filename_charset)
/**
* g_filename_to_utf8:
* @opsysstring: a string in the encoding for filenames
* @opsysstring: (type filename): a string in the encoding for filenames
* @len: the length of the string, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
......@@ -1689,9 +1689,9 @@ g_filename_from_uri (const gchar *uri,
/**
* g_filename_to_uri:
* @filename: an absolute filename specified in the GLib file name encoding,
* which is the on-disk file name bytes on Unix, and UTF-8 on
* Windows
* @filename: (type filename): an absolute filename specified in the GLib file
* name encoding, which is the on-disk file name bytes on Unix, and UTF-8
* on Windows
* @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
......@@ -1839,7 +1839,8 @@ g_uri_list_extract_uris (const gchar *uri_list)
/**
* g_filename_display_basename:
* @filename: an absolute pathname in the GLib file name encoding
* @filename: (type filename): an absolute pathname in the
* GLib file name encoding
*
* Returns the display basename for the particular filename, guaranteed
* to be valid UTF-8. The display name might not be identical to the filename,
......@@ -1879,7 +1880,8 @@ g_filename_display_basename (const gchar *filename)
/**
* g_filename_display_name:
* @filename: a pathname hopefully in the GLib file name encoding
* @filename: (type filename): a pathname hopefully in the
* GLib file name encoding
*
* Converts a filename into a valid UTF-8 string. The conversion is
* not necessarily reversible, so you should keep the original around
......
......@@ -241,7 +241,7 @@ g_dir_new_from_dirp (gpointer dirp)
* On Windows, as is true of all GLib functions which operate on
* filenames, the returned name is in UTF-8.
*
* Returns: The entry's name or %NULL if there are no
* Returns: (type filename): The entry's name or %NULL if there are no
* more entries. The return value is owned by GLib and
* must not be modified or freed.
**/
......
......@@ -67,15 +67,15 @@ g_environ_find (gchar **envp,
/**
* g_environ_getenv:
* @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment
* list (eg, as returned from g_get_environ()), or %NULL
* @envp: (allow-none) (array zero-terminated=1) (transfer none) (element-type filename):
* an environment list (eg, as returned from g_get_environ()), or %NULL
* for an empty environment list
* @variable: the environment variable to get
* @variable: (type filename): the environment variable to get
*
* Returns the value of the environment variable @variable in the
* provided list @envp.
*
* Returns: the value of the environment variable, or %NULL if
* Returns: (type filename): the value of the environment variable, or %NULL if
* the environment variable is not set in @envp. The returned
* string is owned by @envp, and will be freed if @variable is
* set or unset again.
......@@ -99,19 +99,20 @@ g_environ_getenv (gchar **envp,
/**
* g_environ_setenv:
* @envp: (allow-none) (array zero-terminated=1) (transfer full): an
* environment list that can be freed using g_strfreev() (e.g., as
* @envp: (allow-none) (array zero-terminated=1) (element-type filename) (transfer full):
* an environment list that can be freed using g_strfreev() (e.g., as
* returned from g_get_environ()), or %NULL for an empty
* environment list
* @variable: the environment variable to set, must not contain '='
* @value: the value for to set the variable to
* @variable: (type filename): the environment variable to set, must not
* contain '='
* @value: (type filename): the value for to set the variable to
* @overwrite: whether to change the variable if it already exists
*
* Sets the environment variable @variable in the provided list
* @envp to @value.
*
* Returns: (array zero-terminated=1) (transfer full): the
* updated environment list. Free it using g_strfreev().
* Returns: (array zero-terminated=1) (element-type filename) (transfer full):
* the updated environment list. Free it using g_strfreev().
*
* Since: 2.32
*/
......@@ -186,16 +187,17 @@ g_environ_unsetenv_internal (gchar **envp,
/**
* g_environ_unsetenv:
* @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment
* list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
* or %NULL for an empty environment list
* @variable: the environment variable to remove, must not contain '='
* @envp: (allow-none) (array zero-terminated=1) (element-type filename) (transfer full):
* an environment list that can be freed using g_strfreev() (e.g., as
* returned from g_get_environ()), or %NULL for an empty environment list
* @variable: (type filename): the environment variable to remove, must not
* contain '='
*
* Removes the environment variable @variable from the provided
* environment @envp.
*
* Returns: (array zero-terminated=1) (transfer full): the
* updated environment list. Free it using g_strfreev().
* Returns: (array zero-terminated=1) (element-type filename) (transfer full):
* the updated environment list. Free it using g_strfreev().
*
* Since: 2.32
*/
......@@ -217,7 +219,7 @@ g_environ_unsetenv (gchar **envp,
/**
* g_getenv:
* @variable: the environment variable to get
* @variable: (type filename): the environment variable to get
*
* Returns the value of an environment variable.
*
......@@ -227,7 +229,7 @@ g_environ_unsetenv (gchar **envp,
* On Windows, in case the environment variable's value contains
* references to other environment variables, they are expanded.
*
* Returns: the value of the environment variable, or %NULL if
* Returns: (type filename): the value of the environment variable, or %NULL if
* the environment variable is not found. The returned string
* may be overwritten by the next call to g_getenv(), g_setenv()
* or g_unsetenv().
......@@ -242,8 +244,9 @@ g_getenv (const gchar *variable)
/**
* g_setenv:
* @variable: the environment variable to set, must not contain '='.
* @value: the value for to set the variable to.
* @variable: (type filename): the environment variable to set, must not
* contain '='.
* @value: (type filename): the value for to set the variable to.
* @overwrite: whether to change the variable if it already exists.
*
* Sets an environment variable. On UNIX, both the variable's name and
......@@ -311,7 +314,8 @@ extern char **environ;
/**
* g_unsetenv:
* @variable: the environment variable to remove, must not contain '='
* @variable: (type filename): the environment variable to remove, must
* not contain '='
*
* Removes an environment variable from the environment.
*
......@@ -361,8 +365,9 @@ g_unsetenv (const gchar *variable)
* use cases for environment variables in GLib-using programs you want
* the UTF-8 encoding that this function and g_getenv() provide.
*
* Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
* list of strings which must be freed with g_strfreev().
* Returns: (array zero-terminated=1) (element-type filename) (transfer full):
* a %NULL-terminated list of strings which must be freed with
* g_strfreev().
*
* Since: 2.8
*/
......@@ -402,8 +407,8 @@ g_listenv (void)
* The return value is freshly allocated and it should be freed with
* g_strfreev() when it is no longer needed.
*
* Returns: (array zero-terminated=1) (transfer full): the list of
* environment variables
* Returns: (array zero-terminated=1) (element-type filename) (transfer full):
* the list of environment variables
*
* Since: 2.28
*/
......
......@@ -194,7 +194,7 @@
/**
* g_mkdir_with_parents:
* @pathname: a pathname in the GLib file name encoding
* @pathname: (type filename): a pathname in the GLib file name encoding
* @mode: permissions to use for newly created directories
*
* Create a directory if it doesn't already exist. Create intermediate
......@@ -266,7 +266,8 @@ g_mkdir_with_parents (const gchar *pathname,
/**
* g_file_test:
* @filename: a filename to test in the GLib file name encoding
* @filename: (type filename): a filename to test in the
* GLib file name encoding
* @test: bitfield of #GFileTest flags
*
* Returns %TRUE if any of the tests in the bitfield @test are
......@@ -1365,7 +1366,7 @@ wrap_g_open (const gchar *filename,
* in the GLib file name encoding. Most importantly, on Windows it
* should be in UTF-8.
*
* Returns: A pointer to @tmpl, which has been modified
* Returns: (type filename): A pointer to @tmpl, which has been modified
* to hold the directory name. In case of errors, %NULL is
* returned, and %errno will be set.
*
......@@ -1397,7 +1398,7 @@ g_mkdtemp_full (gchar *tmpl,
* The string should be in the GLib file name encoding. Most importantly,
* on Windows it should be in UTF-8.
*
* Returns: A pointer to @tmpl, which has been modified
* Returns: (type filename): A pointer to @tmpl, which has been modified
* to hold the directory name. In case of errors, %NULL is
* returned and %errno will be set.
*
......@@ -1745,13 +1746,15 @@ g_build_path_va (const gchar *separator,
/**
* g_build_pathv:
* @separator: a string used to separator the elements of the path.
* @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
* @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
* array of strings containing the path elements.
*
* Behaves exactly like g_build_path(), but takes the path elements
* as a string array, instead of varargs. This function is mainly
* meant for language bindings.
*
* Returns: a newly-allocated string that must be freed with g_free().
* Returns: (type filename): a newly-allocated string that must be freed
* with g_free().
*
* Since: 2.8
*/
......@@ -1936,13 +1939,15 @@ g_build_pathname_va (const gchar *first_element,
/**
* g_build_filenamev:
* @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
* @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
* array of strings containing the path elements.
*
* Behaves exactly like g_build_filename(), but takes the path elements
* as a string array, instead of varargs. This function is mainly
* meant for language bindings.
*
* Returns: a newly-allocated string that must be freed with g_free().
* Returns: (type filename): a newly-allocated string that must be freed
* with g_free().
*
* Since: 2.8
*/
......@@ -2003,15 +2008,15 @@ g_build_filename (const gchar *first_element,
/**
* g_file_read_link:
* @filename: the symbolic link
* @filename: (type filename): the symbolic link
* @error: return location for a #GError
*
* Reads the contents of the symbolic link @filename like the POSIX
* readlink() function. The returned string is in the encoding used
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
*
* Returns: A newly-allocated string with the contents of the symbolic link,
* or %NULL if an error occurred.
* Returns: (type filename): A newly-allocated string with the contents of
* the symbolic link, or %NULL if an error occurred.
*
* Since: 2.4
*/
......@@ -2062,7 +2067,7 @@ g_file_read_link (const gchar *filename,
/**
* g_path_is_absolute:
* @file_name: a file name
* @file_name: (type filename): a file name
*
* Returns %TRUE if the given @file_name is an absolute file name.
* Note that this is a somewhat vague concept on Windows.
......@@ -2111,13 +2116,14 @@ g_path_is_absolute (const gchar *file_name)
/**
* g_path_skip_root:
* @file_name: a file name
* @file_name: (type filename): a file name
*
* Returns a pointer into @file_name after the root component,
* i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
* is not an absolute path it returns %NULL.
*
* Returns: (nullable): a pointer into @file_name after the root component
* Returns: (type filename) (nullable): a pointer into @file_name after the
* root component
*/
const gchar *
g_path_skip_root (const gchar *file_name)
......@@ -2181,13 +2187,13 @@ g_path_skip_root (const gchar *file_name)
/**
* g_basename:
* @file_name: the name of the file
* @file_name: (type filename): the name of the file
*
* Gets the name of the file without any leading directory
* components. It returns a pointer into the given file name
* string.
*
* Returns: the name of the file without any leading
* Returns: (type filename): the name of the file without any leading
* directory components
*
* Deprecated:2.2: Use g_path_get_basename() instead, but notice
......@@ -2226,7 +2232,7 @@ g_basename (const gchar *file_name)
/**
* g_path_get_basename:
* @file_name: the name of the file
* @file_name: (type filename): the name of the file
*
* Gets the last component of the filename.
*
......@@ -2235,7 +2241,7 @@ g_basename (const gchar *file_name)
* separators (and on Windows, possibly a drive letter), a single
* separator is returned. If @file_name is empty, it gets ".".
*
* Returns: a newly allocated string containing the last
* Returns: (type filename): a newly allocated string containing the last
* component of the filename
*/
gchar *
......@@ -2303,14 +2309,14 @@ g_path_get_basename (const gchar *file_name)
/**
* g_path_get_dirname:
* @file_name: the name of the file
* @file_name: (type filename): the name of the file
*
* Gets the directory components of a file name.
*
* If the file name has no directory components "." is returned.
* The returned string should be freed when no longer needed.
*
* Returns: the directory components of the file
* Returns: (type filename): the directory components of the file
*/
gchar *
g_path_get_dirname (const gchar *file_name)
......@@ -2430,7 +2436,7 @@ g_path_get_dirname (const gchar *file_name)
* the current directory. This can make a difference in the case that
* the current directory is the target of a symbolic link.
*
* Returns: the current directory
* Returns: (type filename): the current directory
*/
gchar *
g_get_current_dir (void)
......
......@@ -421,7 +421,7 @@ g_io_channel_seek (GIOChannel *channel,
/**
* g_io_channel_new_file:
* @filename: A string containing the name of a file
* @filename: (type filename): A string containing the name of a file
* @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
* the same meaning as in fopen()
* @error: A location to return an error of type %G_FILE_ERROR
......
......@@ -212,7 +212,8 @@ mapped_file_new_from_fd (int fd,
/**
* g_mapped_file_new:
* @filename: The path of the file to load, in the GLib filename encoding
* @filename: (type filename): The path of the file to load, in the GLib
* filename encoding
* @writable: whether the mapping should be writable
* @error: return location for a #GError, or %NULL
*
......
......@@ -190,7 +190,7 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
/**
* g_shell_quote:
* @unquoted_string: a literal string
* @unquoted_string: (type filename): a literal string
*
* Quotes a string so that the shell (/bin/sh) will interpret the
* quoted string to mean @unquoted_string. If you pass a filename to
......@@ -199,7 +199,7 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
* quoting style used is undefined (single or double quotes may be
* used).
*
* Returns: quoted string
* Returns: (type filename): quoted string
**/
gchar*
g_shell_quote (const gchar *unquoted_string)
......@@ -240,7 +240,7 @@ g_shell_quote (const gchar *unquoted_string)
/**
* g_shell_unquote:
* @quoted_string: shell-quoted string
* @quoted_string: (type filename): shell-quoted string
* @error: error return location or NULL
*
* Unquotes a string as the shell (/bin/sh) would. Only handles
......@@ -265,7 +265,7 @@ g_shell_quote (const gchar *unquoted_string)
* be escaped with backslash. Otherwise double quotes preserve things
* literally.
*
* Returns: an unquoted string
* Returns: (type filename): an unquoted string
**/
gchar*
g_shell_unquote (const gchar *quoted_string,
......@@ -618,10 +618,10 @@ tokenize_command_line (const gchar *command_line,
/**
* g_shell_parse_argv:
* @command_line: command line to parse
* @command_line: (type filename): command line to parse
* @argcp: (out) (optional): return location for number of args
* @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
* location for array of args
* @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
* return location for array of args
* @error: (optional): return location for error
*
* Parses a command line into an argument vector, in much the same way
......
......@@ -105,9 +105,12 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
/**
* g_spawn_async:
* @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1): child's argument vector
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
* @working_directory: (type filename) (allow-none): child's current working
* directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1) (element-type filename):
* child's argument vector
* @envp: (array zero-terminated=1) (element-type filename) (allow-none):
* child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (allow-none): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
......@@ -215,9 +218,12 @@ read_data (GString *str,
/**
* g_spawn_sync:
* @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1): child's argument vector
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
* @working_directory: (type filename) (allow-none): child's current working
* directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1) (element-type filename):
* child's argument vector
* @envp: (array zero-terminated=1) (element-type filename) (allow-none):
* child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (allow-none): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
......@@ -467,9 +473,13 @@ g_spawn_sync (const gchar *working_directory,
/**
* g_spawn_async_with_pipes:
* @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
* @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
* @working_directory: (type filename) (allow-none): child's current working
* directory, or %NULL to inherit parent's, in the GLib file name encoding
* @argv: (array zero-terminated=1) (element-type filename): child's argument
* vector, in the GLib file name encoding
* @envp: (array zero-terminated=1) (element-type filename) (allow-none):
* child's environment, or %NULL to inherit parent's, in the GLib file
* name encoding
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (allow-none): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
......@@ -676,7 +686,7 @@ g_spawn_async_with_pipes (const gchar *working_directory,
/**
* g_spawn_command_line_sync:
* @command_line: a command line
* @command_line: (type filename): a command line
* @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output
* @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child errors
* @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid()
......@@ -741,7 +751,7 @@ g_spawn_command_line_sync (const gchar *command_line,
/**
* g_spawn_command_line_async:
* @command_line: a command line
* @command_line: (type filename): a command line
* @error: return location for errors
*
* A simple version of g_spawn_async() that parses a command line with
......
......@@ -56,7 +56,8 @@
/**
* g_access:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: as in access()
*
* A wrapper for the POSIX access() function. This function is used to
......@@ -111,7 +112,8 @@ g_access (const gchar *filename,
/**
* g_chmod:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: as in chmod()
*
* A wrapper for the POSIX chmod() function. The chmod() function is
......@@ -157,7 +159,8 @@ g_chmod (const gchar *filename,
}
/**
* g_open:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @flags: as in open()
* @mode: as in open()
*
......@@ -220,7 +223,8 @@ g_open (const gchar *filename,
/**
* g_creat:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: as in creat()
*
* A wrapper for the POSIX creat() function. The creat() function is
......@@ -278,8 +282,9 @@ g_creat (const gchar *filename,
/**
* g_rename:
* @oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @newfilename: a pathname in the GLib file name encoding
* @oldfilename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @newfilename: (type filename): a pathname in the GLib file name encoding
*
* A wrapper for the POSIX rename() function. The rename() function
* renames a file, moving it between directories if required.
......@@ -350,7 +355,8 @@ g_rename (const gchar *oldfilename,
/**
* g_mkdir:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: permissions to use for the newly created directory
*
* A wrapper for the POSIX mkdir() function. The mkdir() function
......@@ -393,7 +399,8 @@ g_mkdir (const gchar *filename,
/**
* g_chdir:
* @path: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @path: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
*
* A wrapper for the POSIX chdir() function. The function changes the
* current directory of the process to @path.
......@@ -440,7 +447,8 @@ g_chdir (const gchar *path)
*/
/**
* g_stat:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @buf: a pointer to a stat struct, which will be filled with the file
* information
*
......@@ -507,7 +515,8 @@ g_stat (const gchar *filename,
/**
* g_lstat:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @buf: a pointer to a stat struct, which will be filled with the file
* information
*
......@@ -538,7 +547,8 @@ g_lstat (const gchar *filename,
/**
* g_unlink:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
*
* A wrapper for the POSIX unlink() function. The unlink() function
* deletes a name from the filesystem. If this was the last link to the
......@@ -582,7 +592,8 @@ g_unlink (const gchar *filename)
/**
* g_remove:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
*
* A wrapper for the POSIX remove() function. The remove() function
* deletes a name from the filesystem.
......@@ -636,7 +647,8 @@ g_remove (const gchar *filename)
/**
* g_rmdir:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
*
* A wrapper for the POSIX rmdir() function. The rmdir() function
* deletes a directory from the filesystem.
......@@ -677,7 +689,8 @@ g_rmdir (const gchar *filename)
/**
* g_fopen:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: a string describing the mode in which the file should be opened
*
* A wrapper for the stdio fopen() function. The fopen() function
......@@ -737,7 +750,8 @@ g_fopen (const gchar *filename,
/**
* g_freopen:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @mode: a string describing the mode in which the file should be opened
* @stream: (allow-none): an existing stream which will be reused, or %NULL
*
......@@ -792,7 +806,8 @@ g_freopen (const gchar *filename,
/**
* g_utime:
* @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
* @filename: (type filename): a pathname in the GLib file name encoding
* (UTF-8 on Windows)
* @utb: a pointer to a struct utimbuf.
*
* A wrapper for the POSIX utime() function. The utime() function
......
......@@ -3447,7 +3447,7 @@ g_test_build_filename (GTestFileType 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
* Returns: (type filename): the path of the directory, owned by GLib
*
* Since: 2.38
**/
......
......@@ -298,7 +298,7 @@ g_find_program_in_path (const gchar *program)
/**
* g_find_program_in_path:
* @program: a program name in the GLib file name encoding
* @program: (type filename): a program name in the GLib file name encoding
*
* Locates the first executable named @program in the user's path, in the
* same way that execvp() would locate it. Returns an allocated string
......@@ -318,7 +318,8 @@ g_find_program_in_path (const gchar *program)
* the program is found, the return value contains the full name
* including the type suffix.
*
* Returns: a newly-allocated string with the absolute path, or %NULL
* Returns: (type filename): a newly-allocated string with the absolute path,
* or %NULL
**/
#ifdef G_OS_WIN32
static gchar *
......@@ -750,7 +751,7 @@ g_get_user_database_entry (void)
* encoding, or something else, and there is no guarantee that it is even
* consistent on a machine. On Windows, it is always UTF-8.
*
* Returns: the user name of the current user.
* Returns: (type filename): the user name of the current user.
*/
const gchar *
g_get_user_name (void)
......@@ -771,7 +772,7 @@ g_get_user_name (void)
* real user name cannot be determined, the string "Unknown" is
* returned.
*
* Returns: the user's real name.
* Returns: (type filename): the user's real name.
*/
const gchar *
g_get_real_name (void)
......@@ -807,7 +808,7 @@ g_get_real_name (void)
* should either directly check the `HOME` environment variable yourself
* or unset it before calling any functions in GLib.
*
* Returns: the current user's home directory
* Returns: (type filename): the current user's home directory
*/
const gchar *
g_get_home_dir (void)
......@@ -903,7 +904,7 @@ g_get_home_dir (void)
* it is always UTF-8. The return value is never %NULL or the empty
* string.
*
* Returns: the directory to use for temporary files.
* Returns: (type filename): the directory to use for temporary files.
*/
const gchar *
g_get_tmp_dir (void)
......@@ -1145,7 +1146,7 @@ g_set_application_name (const gchar *application_name)
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
*
* Returns: a string owned by GLib that must not be modified
* Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
**/
......@@ -1231,7 +1232,7 @@ g_init_user_config_dir (void)
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_data_dir() returns.
*
* Returns: a string owned by GLib that must not be modified
* Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
**/
......@@ -1263,7 +1264,7 @@ g_get_user_config_dir (void)
* C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
* See documentation for CSIDL_INTERNET_CACHE.
*
* Returns: a string owned by GLib that must not be modified
* Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
**/
......@@ -1322,7 +1323,8 @@ g_get_user_cache_dir (void)
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
*
* Returns: a string owned by GLib that must not be modified or freed.
* Returns: (type filename): a string owned by GLib that must not be
* modified or freed.
*
* Since: 2.28
**/
......@@ -1718,8 +1720,8 @@ g_reload_user_special_dirs_cache (void)
* of the special directory without requiring the session to restart; GLib
* will not reflect any change once the special directories are loaded.
*
* Returns: the path to the specified special directory, or %NULL
* if the logical id was not found. The returned string is owned by
* Returns: (type filename): the path to the specified special directory, or
* %NULL if the logical id was not found. The returned string is owned by
* GLib and should not be modified or freed.
*
* Since: 2.14
......@@ -1936,8 +1938,10 @@ g_win32_get_system_data_dirs_for_module (void (*address_of_function)(void))
* Note that on Windows the returned list can vary depending on where
* this function is called.
*
* Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
* not be modified or freed.
* Returns: (array zero-terminated=1) (element-type filename) (transfer none):
* a %NULL-terminated array of strings owned by GLib that must not be
* modified or freed.
*
* Since: 2.6
**/
const gchar * const *
......@@ -1988,8 +1992,10 @@ g_get_system_data_dirs (void)
* of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
* This information will not roam and is available to anyone using the computer.
*
* Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
* not be modified or freed.
* Returns: (array zero-terminated=1) (element-type filename) (transfer none):
* a %NULL-terminated array of strings owned by GLib that must not be
* modified or freed.
*
* Since: 2.6
**/