![]() |
![]() |
![]() |
PolicyKit Library Reference Manual | ![]() |
---|---|---|---|---|
char* kit_strdup (const char *s); char* kit_strndup (const char *s, size_t n); char* kit_strdup_printf (const char *format, ...); char* kit_strdup_vprintf (const char *format, va_list args); char* kit_str_append (char *s, const char *s2); kit_bool_t kit_str_has_prefix (const char *s, const char *prefix); kit_bool_t kit_str_has_suffix (const char *s, const char *suffix); char** kit_strsplit (const char *s, char delim, size_t *num_tokens); void kit_strfreev (char **str_array); size_t kit_strv_length (char **str_array); kit_bool_t (*KitStringEntryParseFunc) (const char *key, const char *value, void *user_data); kit_bool_t kit_string_entry_parse (const char *entry, KitStringEntryParseFunc func, void *user_data); kit_bool_t kit_string_percent_decode (char *s); size_t kit_string_percent_encode (char *buf, size_t buf_size, const char *s); size_t kit_string_entry_create (char *buf, size_t buf_size, ...); size_t kit_string_entry_createv (char *buf, size_t buf_size, const char *kv_pairs[]); KitString; KitString* kit_string_new (const char *init, size_t len); char* kit_string_free (KitString *s, kit_bool_t free_segment, size_t *out_segment_size); kit_bool_t kit_string_ensure_size (KitString *s, size_t new_size); kit_bool_t kit_string_append_c (KitString *s, char c); kit_bool_t kit_string_append (KitString *s, const char *str);
char* kit_strdup (const char *s);
Duplicate a string. Similar to strdup(3).
|
string |
Returns : |
Allocated memory or NULL on OOM. Free with kit_free() .
|
char* kit_strndup (const char *s, size_t n);
Duplicate a string but copy at most n
characters. If s
is longer
than n
, only n
characters are copied, and a terminating null byte
is added. Similar to strndup(3).
|
string |
|
size |
Returns : |
Allocated memory or NULL on OOM. Free with kit_free() .
|
char* kit_strdup_printf (const char *format, ...);
Similar to the standard C sprintf(3) function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.
|
sprintf(3) format string |
|
the parameters to insert into the format string. |
Returns : |
A newly allocated string or NULL on OOM. Free with kit_free() .
|
char* kit_strdup_vprintf (const char *format, va_list args);
Similar to the standard C vsprintf(3) function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.
|
printf(3) format string |
|
list of parameters to insert |
Returns : |
A newly allocated string or NULL on OOM. Free with kit_free() .
|
char* kit_str_append (char *s, const char *s2);
Append a string to an existing string.
|
either NULL or a string previously allocated on the heap
|
|
string to append |
Returns : |
NULL on OOM or the new string; possibly at the same
location as s .
|
kit_bool_t kit_str_has_prefix (const char *s, const char *prefix);
Determines if a string has a given prefix.
|
string to check |
|
prefix to check for |
Returns : |
TRUE only if s starts with prefix
|
kit_bool_t kit_str_has_suffix (const char *s, const char *suffix);
Determines if a string has a given suffix.
|
string to check |
|
suffix to check for |
Returns : |
TRUE only if s ends with suffix
|
char** kit_strsplit (const char *s, char delim, size_t *num_tokens);
Split a given string into components given a delimiter.
|
string to split |
|
delimiter used for splitting |
|
return location for number of elements or NULL |
Returns : |
A NULL terminated array of strings. Free with kit_strfreev() . Returns NULL on OOM.
|
void kit_strfreev (char **str_array);
Free a NULL terminated string array.
|
string array |
size_t kit_strv_length (char **str_array);
Compute number of elements in a NULL terminated string array.
|
string array |
Returns : |
Number of elements not including the terminating NULL |
kit_bool_t (*KitStringEntryParseFunc) (const char *key, const char *value, void *user_data);
Type of callback function to use in kit_string_entry_parse()
|
key of one of the entries |
|
value of one of the entries |
|
user data passed to kit_string_entry_parse()
|
Returns : |
If FALSE is returned the parsing will be aborted and
kit_string_entry_parse() will return FALSE.
|
kit_bool_t kit_string_entry_parse (const char *entry, KitStringEntryParseFunc func, void *user_data);
Parse a line of the form
key1=val1:key2=val2:key3=val3
.
The given entry
is said not to be wellformed if a) it doesn't
follow this structure (for example
key1=val1:key2:key3=val3
is not well-formed
because it's missing the '=' character) or the extracted key and
value strings are not properly percent encoded.
Both the key and value values are run through the
kit_string_percent_decode()
function prior to being passed to
func
. Normally this function is used to decode strings produced
with kit_string_entry_create()
.
|
line to parse |
|
callback function |
|
user data to pass to func
|
Returns : |
TRUE if the line is wellformed and the callback didn't
short-circuit the iteration. Returns FALSE on OOM (and errno will
be set to ENOMEM) or if entry is not wellformed (and errno will
be set to EINVAL).
|
kit_bool_t kit_string_percent_decode (char *s);
Percent-decodes a string in place. See kit_string_percent_encode()
for details on the encoding format.
|
string to modify in place |
Returns : |
FALSE if string is not properly encoded (and errno will be set to EINVAL)
|
size_t kit_string_percent_encode (char *buf, size_t buf_size, const char *s);
Percent encodes a string; each occurence of an ASCII characters in
the set " !*'();:@&=+$,/?%#[]\n\r\t"
will be
replaced by a three character sequence started by the percent sign
"%" and then the hexidecimal representation of the ASCII character
in question.
|
return location for output |
|
size of buffer |
|
string to encode |
Returns : |
This function do not write more than buf_size bytes
(including the trailing zero). If the output was truncated due to
this limit then the return value is the number of characters (not
including the trailing zero) which would have been written to the
final string if enough space had been available. Thus, a return
value of buf_size or more means that the output was truncated.
|
size_t kit_string_entry_create (char *buf, size_t buf_size, ...);
See kit_string_entry_create()
.
|
return location for output |
|
size of buffer |
|
NULL terminated array of key/value pairs.
|
Returns : |
See kit_string_entry_create() . Up to 64 pairs can be
passed; if there are more pairs, this function will return zero and
errno will be set to EOVERFLOW.
|
size_t kit_string_entry_createv (char *buf, size_t buf_size, const char *kv_pairs[]);
Takes an array of key/value pairs and generates a string
"k1=v1:k2=v2:...:k_n=v_n"
where
k_i
and v_i
are percent
encoded representations of the given key/value pairs.
The string can later be parsed with kit_string_entry_parse()
to get
the exact same list of key/value pairs back.
|
return location for output |
|
size of buffer |
|
NULL terminated array of key/value pairs.
|
Returns : |
This function do not write more than buf_size bytes
(including the trailing zero). If the output was truncated due to
this limit then the return value is the number of characters (not
including the trailing zero) which would have been written to the
final string if enough space had been available. Thus, a return
value of buf_size or more means that the output was truncated.
If an uneven number of strings are given, this function will return
zero and errno will be set to EINVAL.
|
typedef struct _KitString KitString;
String buffer that grows automatically as text is added.
KitString* kit_string_new (const char *init, size_t len);
Initialize a new KitString object.
|
String to initialize with or NULL
|
|
Initial size of buffer; pass zero to use the default size |
Returns : |
The new object or NULL on OOM
|
char* kit_string_free (KitString *s, kit_bool_t free_segment, size_t *out_segment_size);
Free resources used by a KitString object
|
the KitString object |
|
whether to free the string data itself |
|
return location for size of string or NULL
|
Returns : |
If free_segment is TRUE , returns the segment (will
always be zero terminated), must be freed with kit_free() ,
otherwise NULL
|
kit_bool_t kit_string_ensure_size (KitString *s, size_t new_size);
Ensure that the given KitString object can hold at least new_size
characters.
|
String object |
|
The size to check for. |
Returns : |
TRUE if the given KitString object can hold at least
new_size characters. FALSE if OOM.
|
kit_bool_t kit_string_append_c (KitString *s, char c);
Append a character to a KitString object.
|
the KitString object |
|
character to append |
Returns : |
TRUE unless OOM
|
kit_bool_t kit_string_append (KitString *s, const char *str);
Append a string to a KitString object.
|
the KitString object |
|
string to append |
Returns : |
TRUE unless OOM
|