diff options
| -rw-r--r-- | doc/SystemTap_Tapset_Reference/tapsets.tmpl | 9 | ||||
| -rw-r--r-- | tapset/string.stp | 129 |
2 files changed, 85 insertions, 53 deletions
diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl index bb855d29..c60bc22f 100644 --- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl +++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl @@ -262,6 +262,15 @@ </para> !Itapset/conversions.stp </chapter> + <chapter id="string.stp"> + <title>A collection of standard string functions</title> + <para> + Functions to get the length, a substring, getting at individual + characters, string seaching, escaping, tokenizing, and converting + strings to longs. + </para> +!Itapset/string.stp + </chapter> <chapter id="ansi.stp"> <title>Utility functions for using ansi control chars in logs</title> <para> diff --git a/tapset/string.stp b/tapset/string.stp index 92750b6b..59ba74ee 100644 --- a/tapset/string.stp +++ b/tapset/string.stp @@ -1,36 +1,45 @@ -/** @addtogroup library -* The library tapset is a collection of standard functions. -* @{ -*/ +// Standard string functions tapset. +// Copyright (C) 2009 Red Hat, Inc. +// +// This file is part of systemtap, and is free software. You can +// redistribute it and/or modify it under the terms of the GNU General +// Public License (GPL); either version 2, or (at your option) any +// later version. -/** @addtogroup library -* @code function strlen:long(s:string) @endcode -* @param s string -* @return Returns the length of the string. -*/ +/** + * sfunction strlen - Returns the length of a string. + * @s: the string + * + * Description: Returns the lenght of the string, which can be zero up + * to MAXSTRINGLEN. + */ function strlen:long(s:string) %{ /* pure */ /* unprivileged */ THIS->__retvalue = strlen(THIS->s); %} -/** @addtogroup library -* @code function substr:string(str:string,start:long,length:long) @endcode -* @param str string -* @param start Starting position. 0 = start of the string -* @param length Length of string to return. -* @return Returns the substring. -*/ +/** + * sfunction substr - Returns a substring. + * @str: The string to take a substring from + * @start: Starting position. 0 = start of the string. + * @length: Length of string to return. + * + * Description: Returns the substring of the up to the given length + * starting at the given start position. + */ function substr:string(str:string,start:long, length:long) %{ /* pure */ /* unprivileged */ int length = THIS->length >= MAXSTRINGLEN ? MAXSTRINGLEN : THIS->length + 1; if (THIS->start >= 0 && length > 0 && THIS->start < strlen(THIS->str)) strlcpy(THIS->__retvalue, THIS->str + THIS->start, length); %} -/** @addtogroup library -* @code function stringat:string(str:string, pos:long) @endcode -* @param str string -* @param pos the given position. 0 = start of the string -* @return Returns the char in given position of string. -*/ +/** + * sfunction stringat - Returns the char at a given position in the string. + * @str: The string to fetch the character from. + * @pos: The position to get the character from. 0 = start of the string. + * + * Returns the character at a given position in the string or zero if the + * string doesn't have as many characters. + */ function stringat:long(str:string, pos:long) %{ /* pure */ /* unprivileged */ if (THIS->pos >= 0 && THIS->pos < strlen(THIS->str)) THIS->__retvalue = THIS->str[THIS->pos]; @@ -38,12 +47,13 @@ function stringat:long(str:string, pos:long) %{ /* pure */ /* unprivileged */ THIS->__retvalue = 0; %} -/** @addtogroup library -* @code isinstr:long(s1:string,s2:string) @endcode -* @param s1 string -* @param s2 string -* @return Returns 1 if s2 is in s1. Otherwise 0. -*/ +/** + * sfunction isinstr - Returns whether a string is a substring of another string. + * @s1: String to search in. + * @s2: Substring to find. + * + * Description: Returns 1 if s2 is in s1, otherwise 0. + */ function isinstr:long(s1:string,s2:string) %{ /* pure */ /* unprivileged */ if (strstr(THIS->s1,THIS->s2) != NULL) THIS->__retvalue = 1; @@ -51,30 +61,44 @@ function isinstr:long(s1:string,s2:string) %{ /* pure */ /* unprivileged */ THIS->__retvalue = 0; %} -/* - * text_str() +/** + * sfunction text_str - Escape any non-printable chars in a string. + * @input: The string to escape. * - * Takes a string, and any ASCII characters that are not printable are - * replaced by the corresponding escape sequence in the returned - * string. + * Description Takes a string, and any ASCII characters that are not + * printable are replaced by the corresponding escape sequence in the + * returned string. */ function text_str:string(input:string) %{ /* pure */ /* unprivileged */ _stp_text_str(THIS->__retvalue, THIS->input, 0, 0, 0); %} +/** + * sfunction text_strn - Escape any non-printable chars in a string. + * @input: The string to escape. + * @len: Maximum length of string to return. 0 means MAXSTRINGLEN. + * @quoted: Put double quotes around the string. If input string is + * truncated it will have "..." after the second quote. + * + * Description Takes a string, and any ASCII characters that are not + * printable are replaced by the corresponding escape sequence in the + * returned string. + */ function text_strn:string(input:string, len:long, quoted:long) %{ /* pure */ /* unprivileged */ _stp_text_str(THIS->__retvalue, THIS->input, THIS->len, THIS->quoted, 0); %} -/* - * tokenize - Given a string and a token delimiter, - * return the next non-empty token in the string - * or blank when no more non-empty tokens are left - * input String to tokenize. If NULL, returns the next non-empty token - * in the string passed in the previous call to tokenize(). - * delim Token delimiter. Set of characters that delimit the tokens. +/** + * sfunction tokenize - Return the next non-empty token in a string. + * @input: String to tokenize. If NULL, returns the next non-empty token + * in the string passed in the previous call to tokenize(). + * @delim: Token delimiter. Set of characters that delimit the tokens. + * + * Description: Given a string and a token delimiter, return the next + * non-empty token in the string or blank when no more non-empty tokens + * are left. */ function tokenize:string(input:string, delim:string) %{ /* unprivileged */ @@ -98,12 +122,13 @@ function tokenize:string(input:string, delim:string) } %} -/** @addtogroup library - * @code str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) @endcode - * @param prnt_str The parent string. - * @param srch_str The substring which is used to search in the parent string prnt_str. - * @param rplc_str The substring which is used to replace the searched string srch_str. - * @return Returns the parent string with substrings replaced. Else returns parent string. +/** + * sfunction - str_replace Replaces all instances of a substring with another. + * @prnt_str: The string to search and replace in. + * @srch_str: The substring which is used to search in prnt_str string. + * @rplc_str: The substring which is used to replace srch_str. + * + * Description: Returns the given string with substrings replaced. */ function str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) %{ /* pure */ /* unprivileged */ @@ -129,14 +154,12 @@ function str_replace:string (prnt_str:string, srch_str:string, rplc_str:string) return; %} -/* - * strtol - Convert a string to a long - * str String to convert - * base The base to use +/** + * sfunction - strtol - Convert a string to a long. + * @str: String to convert. + * @base: The base to use */ function strtol:long(str:string, base:long) %{ /* pure */ /* unprivileged */ THIS->__retvalue = simple_strtol(THIS->str, NULL, THIS->base); -%} - -/** @} */ +%}
\ No newline at end of file |