luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-20 01:06:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

glib: Add filename type annotations

Browse Source 
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
This commit is contained in:
Christoph Reiter 2016-06-04 15:46:12 +02:00 committed by Christoph Reiter
parent 7d8e98ee09
commit 41013a01f4
12 changed files with 157 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
glib/gbookmarkfile.c
View File

@ -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

14
glib/gconvert.c
View File

@ -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

2
glib/gdir.c
View File

@ -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.
**/

55
glib/genviron.c
View File

@ -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
*/

48
glib/gfileutils.c
View File

@ -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)

2
glib/giochannel.c
View File

@ -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

3
glib/gmappedfile.c
View File

@ -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
*

14
glib/gshell.c
View File

@ -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

32
glib/gspawn.c
View File

@ -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

47
glib/gstdio.c
View File

@ -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

2
glib/gtestutils.c
View File

@ -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
**/

38
glib/gutils.c
View File

@ -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
**/
const gchar * const *