From 6eecdc5fbd217fbc744e6ff91e9b374005e78f1b Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 29 May 2017 19:13:30 -0400 Subject: [PATCH] Docs: add informal comments to common-internal.h MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- include/babeltrace/common-internal.h | 69 ++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/include/babeltrace/common-internal.h b/include/babeltrace/common-internal.h index b843e57e..eb055f5e 100644 --- a/include/babeltrace/common-internal.h +++ b/include/babeltrace/common-internal.h @@ -33,18 +33,40 @@ struct bt_common_lttng_live_url_parts { int port; }; +/* + * Checks if the current process has setuid or setgid access rights. + * Returns `true` if so. + */ BT_HIDDEN bool bt_common_is_setuid_setgid(void); +/* + * Returns the system-wide plugin path, e.g. + * `/usr/lib/babeltrace/plugins`. Do not free the return value. + */ BT_HIDDEN const char *bt_common_get_system_plugin_path(void); +/* + * Returns the user plugin path, e.g. + * `/home/user/.local/lib/babeltrace/plugins`. You need to free the + * return value. + */ BT_HIDDEN char *bt_common_get_home_plugin_path(void); +/* + * Appends the list of directories in `paths` to the array `dirs`. + * `paths` is a list of directories separated by `:`. Returns 0 on + * success. + */ BT_HIDDEN int bt_common_append_plugin_path_dirs(const char *paths, GPtrArray *dirs); +/* + * Returns `true` if terminal color codes are supported for this + * process. + */ BT_HIDDEN bool bt_common_colors_supported(void); @@ -102,31 +124,78 @@ const char *bt_common_color_bg_cyan(void); BT_HIDDEN const char *bt_common_color_bg_light_gray(void); +/* + * Returns the substring from `input` to the first character found + * in the list of characters `end_chars`, unescaping any character + * found in `escapable_chars`, and sets `*end_pos` to the position of + * the end (from `input`). The caller owns the returned GString. + */ BT_HIDDEN GString *bt_common_string_until(const char *input, const char *escapable_chars, const char *end_chars, size_t *end_pos); +/* + * Returns the quoted version of `input` for a shell. If + * `with_single_quotes` is `true`, prepends and appends the `'` prefix + * and suffix to the returned string; otherwise the caller should + * prepend and append them manually, although they are not always + * required. The caller owns the returned GString. + */ BT_HIDDEN GString *bt_common_shell_quote(const char *input, bool with_single_quotes); +/* + * Returns `true` if `input` is a string made only of printable + * characters. + */ BT_HIDDEN bool bt_common_string_is_printable(const char *input); +/* + * Destroys the parts of an LTTng live URL as returned by + * bt_common_parse_lttng_live_url(). + */ BT_HIDDEN void bt_common_destroy_lttng_live_url_parts( struct bt_common_lttng_live_url_parts *parts); +/* + * Parses the LTTng live URL `url` and returns its different parts. + * If there's an error, writes the error message into `*error_buf` + * up to `error_buf_size` bytes. You must destroy the returned value + * with bt_common_destroy_lttng_live_url_parts(). + */ BT_HIDDEN struct bt_common_lttng_live_url_parts bt_common_parse_lttng_live_url( const char *url, char *error_buf, size_t error_buf_size); +/* + * Normalizes (in place) a star globbing pattern to be used with + * bt_common_star_glob_match(). This function always succeeds. + */ BT_HIDDEN void bt_common_normalize_star_glob_pattern(char *pattern); +/* + * Returns `true` if `candidate` (of size `candidate_len`) matches + * the star globbing pattern `pattern` (of size `pattern_len`). + */ BT_HIDDEN bool bt_common_star_glob_match(const char *pattern, size_t pattern_len, const char *candidate, size_t candidate_len); +/* + * Normalizes the path `path`: + * + * * If it's a relative path, converts it to an absolute path using + * `wd` as the working directory (or the current working directory + * if `wd` is NULL). + * * Removes consecutive and trailing slashes. + * * Resolves `..` and `.` in the path (both in `path` and in `wd`). + * * Does NOT resolve symbolic links. + * + * The caller owns the returned GString. + */ BT_HIDDEN GString *bt_common_normalize_path(const char *path, const char *wd); -- 2.34.1