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

introspection: Add more filename type annotations for strings which can contain filenames

Browse Source 
This continues the changes done in https://bugzilla.gnome.org/show_bug.cgi?id=767245

This makes it possible to pass Python path types as process arguments and env vars
in PyGObject and and makes it clear that the values are not strictly utf-8 and need
to be validated/converted first.

https://bugzilla.gnome.org/show_bug.cgi?id=788863
This commit is contained in:
Christoph Reiter 2017-10-11 18:49:11 +02:00
parent 3d35379382
commit fed574a0c8
10 changed files with 86 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
gio/gappinfo.c
View File

@ -987,8 +987,8 @@ g_app_launch_context_init (GAppLaunchContext *context)
/**
* g_app_launch_context_setenv:
* @context: a #GAppLaunchContext
* @variable: the environment variable to set
* @value: the value for to set the variable to.
* @variable: (type filename): the environment variable to set
* @value: (type filename): the value for to set the variable to.
*
* Arranges for @variable to be set to @value in the child's
* environment when @context is used to launch an application.
@ -1010,7 +1010,7 @@ g_app_launch_context_setenv (GAppLaunchContext *context,
/**
* g_app_launch_context_unsetenv:
* @context: a #GAppLaunchContext
* @variable: the environment variable to remove
* @variable: (type filename): the environment variable to remove
*
* Arranges for @variable to be unset in the child's environment
* when @context is used to launch an application.
@ -1037,8 +1037,8 @@ g_app_launch_context_unsetenv (GAppLaunchContext *context,
* This is a %NULL-terminated array of strings, where each string has
* the form `KEY=VALUE`.
*
* Returns: (array zero-terminated=1) (transfer full): the
* child's environment
* Returns: (array zero-terminated=1) (element-type filename) (transfer full):
* the child's environment
*
* Since: 2.32
*/

3
gio/gapplication.c
View File

@ -2218,7 +2218,8 @@ g_application_open (GApplication *application,
* g_application_run:
* @application: a #GApplication
* @argc: the argc from main() (or 0 if @argv is %NULL)
* @argv: (array length=argc) (nullable): the argv from main(), or %NULL
* @argv: (array length=argc) (element-type filename) (nullable):
* the argv from main(), or %NULL
*
* Runs the application.
*

12
gio/gapplicationcommandline.c
View File

@ -463,8 +463,8 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class)
* The return value is %NULL-terminated and should be freed using
* g_strfreev().
*
* Returns: (array length=argc) (transfer full): the string array
* containing the arguments (the argv)
* Returns: (array length=argc) (element-type filename) (transfer full)
* the string array containing the arguments (the argv)
*
* Since: 2.28
**/
@ -582,8 +582,8 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
* See g_application_command_line_getenv() if you are only interested
* in the value of a single environment variable.
*
* Returns: (array zero-terminated=1) (transfer none): the environment
* strings, or %NULL if they were not sent
* Returns: (array zero-terminated=1) (element-type filename) (transfer none):
* the environment strings, or %NULL if they were not sent
*
* Since: 2.28
**/
@ -596,7 +596,7 @@ g_application_command_line_get_environ (GApplicationCommandLine *cmdline)
/**
* g_application_command_line_getenv:
* @cmdline: a #GApplicationCommandLine
* @name: the environment variable to get
* @name: (type filename): the environment variable to get
*
* Gets the value of a particular environment variable of the command
* line invocation, as would be returned by g_getenv(). The strings may
@ -805,7 +805,7 @@ g_application_command_line_get_platform_data (GApplicationCommandLine *cmdline)
/**
* g_application_command_line_create_file_for_arg:
* @cmdline: a #GApplicationCommandLine
* @arg: an argument from @cmdline
* @arg: (type filename): an argument from @cmdline
*
* Creates a #GFile corresponding to a filename that was given as part
* of the invocation of @cmdline.

2
gio/gdesktopappinfo.c
View File

@ -3706,7 +3706,7 @@ g_desktop_app_info_delete (GAppInfo *appinfo)
/* Create for commandline {{{2 */
/**
* g_app_info_create_from_commandline:
* @commandline: the commandline to use
* @commandline: (type filename): the commandline to use
* @application_name: (nullable): the application name, or %NULL to use @commandline
* @flags: flags that can specify details of the created #GAppInfo
* @error: a #GError location to store the error occurring, %NULL to ignore.

4
gio/gfile.c
View File

@ -6498,7 +6498,7 @@ new_for_cmdline_arg (const gchar *arg,
/**
* g_file_new_for_commandline_arg:
* @arg: a command line string
* @arg: (type filename): a command line string
*
* Creates a #GFile with the given argument from the command line.
* The value of @arg can be either a URI, an absolute path or a
@ -6528,7 +6528,7 @@ g_file_new_for_commandline_arg (const char *arg)
/**
* g_file_new_for_commandline_arg_and_cwd:
* @arg: a command line string
* @arg: (type filename): a command line string
* @cwd: (type filename): the current working directory of the commandline
*
* Creates a #GFile with the given argument from the command line.

2
gio/gsubprocess.c
View File

@ -717,7 +717,7 @@ g_subprocess_new (GSubprocessFlags flags,
/**
* g_subprocess_newv: (rename-to g_subprocess_new)
* @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
* @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess
* @flags: flags that define the behaviour of the subprocess
* @error: (nullable): return location for an error, or %NULL
*

18
gio/gsubprocesslauncher.c
View File

@ -228,7 +228,8 @@ g_subprocess_launcher_new (GSubprocessFlags flags)
/**
* g_subprocess_launcher_set_environ:
* @self: a #GSubprocess
* @env: (array zero-terminated=1) (transfer none): the replacement environment
* @env: (array zero-terminated=1) (element-type filename) (transfer none):
* the replacement environment
*
* Replace the entire environment of processes launched from this
* launcher with the given 'environ' variable.
@ -266,8 +267,9 @@ g_subprocess_launcher_set_environ (GSubprocessLauncher *self,
/**
* g_subprocess_launcher_setenv:
* @self: a #GSubprocess
* @variable: the environment variable to set, must not contain '='
* @value: the new value for the variable
* @variable: (type filename): the environment variable to set,
* must not contain '='
* @value: (type filename): the new value for the variable
* @overwrite: whether to change the variable if it already exists
*
* Sets the environment variable @variable in the environment of
@ -291,7 +293,8 @@ g_subprocess_launcher_setenv (GSubprocessLauncher *self,
/**
* g_subprocess_launcher_unsetenv:
* @self: a #GSubprocess
* @variable: the environment variable to unset, must not contain '='
* @variable: (type filename): the environment variable to unset,
* must not contain '='
*
* Removes the environment variable @variable from the environment of
* processes launched from this launcher.
@ -311,7 +314,7 @@ g_subprocess_launcher_unsetenv (GSubprocessLauncher *self,
/**
* g_subprocess_launcher_getenv:
* @self: a #GSubprocess
* @variable: the environment variable to get
* @variable: (type filename): the environment variable to get
*
* Returns the value of the environment variable @variable in the
* environment of processes launched from this launcher.
@ -319,7 +322,8 @@ g_subprocess_launcher_unsetenv (GSubprocessLauncher *self,
* On UNIX, the returned string can be an arbitrary byte string.
* On Windows, it will be UTF-8.
*
* Returns: the value of the environment variable, %NULL if unset
* Returns: (type filename): the value of the environment variable,
* %NULL if unset
*
* Since: 2.40
**/
@ -724,7 +728,7 @@ g_subprocess_launcher_spawn (GSubprocessLauncher *launcher,
/**
* g_subprocess_launcher_spawnv:
* @self: a #GSubprocessLauncher
* @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
* @argv: (array zero-terminated=1) (element-type filename): Command line arguments
* @error: Error
*
* Creates a #GSubprocess given a provided array of arguments.

55
glib/genviron.c
View File

@ -67,15 +67,15 @@ g_environ_find (gchar **envp,
/**
* g_environ_getenv:
* @envp: (nullable) (array zero-terminated=1) (transfer none): an environment
* list (eg, as returned from g_get_environ()), or %NULL
* @envp: (nullable) (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: (nullable) (array zero-terminated=1) (transfer full): an
* environment list that can be freed using g_strfreev() (e.g., as
* @envp: (nullable) (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: (nullable) (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: (nullable) (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
*/

14
glib/gshell.c
View File

@ -188,7 +188,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
@ -197,7 +197,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)
@ -238,7 +238,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
@ -263,7 +263,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,
@ -616,10 +616,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

@ -146,9 +146,12 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
/**
* g_spawn_async:
* @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's
* @working_directory: (type filename) (nullable): 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) (nullable):
* child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
@ -256,9 +259,12 @@ read_data (GString *str,
/**
* g_spawn_sync:
* @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's
* @working_directory: (type filename) (nullable): 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) (nullable):
* child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
@ -509,9 +515,13 @@ g_spawn_sync (const gchar *working_directory,
/**
* g_spawn_async_with_pipes:
* @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
* @working_directory: (type filename) (nullable): 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) (nullable):
* child's environment, or %NULL to inherit parent's, in the GLib file
* name encoding
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
@ -719,7 +729,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) (optional): return location for child output
* @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors
* @exit_status: (out) (optional): return location for child exit status, as returned by waitpid()
@ -784,7 +794,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