kstrto*: add documentation
Subsystems (3)
PATCH 1/2 kstrto*: add documentation
As J. Bruce Fields <[email protected]> pointed out, kstrto* is currently lacking kerneldoc comments.
This patch adds kerneldoc comments to common variants of kstrto*:
kstrto(u)l, kstrto(u)ll and kstrto(u)int.
Cc J. Bruce Fields <[email protected]>
Signed-off-by Eldad Zack <[email protected]>
---
v2: includes typo fix from Joe Perches <[email protected]>,
added details as suggested by J. Bruce Fields <[email protected]>, added the kstrto* functions to string conversions section in SGML.
Documentation/DocBook/kernel-api.tmpl | 3 ++ include/linux/kernel.h | 33 +++++++++++++++++ lib/kstrtox.c | 64 +++++++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+), 0 deletions(-)
Documentation/DocBook/kernel-api.tmpl +3 -0
@@ -58,6 +58,9 @@ <sect1><title>String Conversions</title> !Elib/vsprintf.c +!Finclude/linux/kernel.h kstrtol +!Finclude/linux/kernel.h kstrtoul +!Elib/kstrtox.c </sect1> <sect1><title>String Manipulation</title> <!-- All functions are exported at now
include/linux/kernel.h +33 -0
@@ -228,6 +228,23 @@ int __must_check _kstrtol(const char *s, unsigned int base, long *res);int __must_check kstrtoull (const char *s,unsigned int base,unsigned long long *res);int __must_check kstrtoll (const char *s,unsigned int base,long long *res); + +/** +* kstrtoul - convert a string to an unsigned long +* @s: The start of the string. The string must be null-terminated, and may also +* include a single newline before its terminating null. The first character +* may also be a plus sign, but not a minus sign. +* @base: The number base to use. The maximum supported base is 16. If base is +* given as 0, then the base of the string is automatically detected with the +* conventional semantics - If it begins with 0x the number will be parsed as a +* hexadecimal (case insensitive), if it otherwise begins with 0, it will be +* parsed as an octal number. Otherwise it will be parsed as a decimal. +* @res: Where to write the result of the conversion on success. +* +* Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. +* Used as a replacement for the obsolete simple_strtoull. Return code must +* be checked. +*/ static inline int __must_check kstrtoul (const char *s,unsigned int base,unsigned long *res) {/*
@@ -241,6 +258,22 @@ static inline int __must_check kstrtoul(const char *s, unsigned int base, unsignreturn _kstrtoul (s, base, res); } +/** +* kstrtol - convert a string to a long +* @s: The start of the string. The string must be null-terminated, and may also +* include a single newline before its terminating null. The first character +* may also be a plus sign or a minus sign. +* @base: The number base to use. The maximum supported base is 16. If base is +* given as 0, then the base of the string is automatically detected with the +* conventional semantics - If it begins with 0x the number will be parsed as a +* hexadecimal (case insensitive), if it otherwise begins with 0, it will be +* parsed as an octal number. Otherwise it will be parsed as a decimal. +* @res: Where to write the result of the conversion on success. +* +* Returns 0 on success, -ERANGE on overflow and -EINVAL on parsing error. +* Used as a replacement for the obsolete simple_strtoull. Return code must +* be checked. +*/ static inline int __must_check kstrtol (const char *s,unsigned int base,long *res) {/*
lib/kstrtox.c +64 -0
88 lines not on this page · raw message
Signature · 1 line
1.7.8.6
PATCH 2/2 simple_strto*: annotate function as obsolete
This patch update the documentation to simple_strto* to reflect that it has been obsoleted and advise the usage of kstrto*.
Cc J. Bruce Fields <[email protected]>
Signed-off-by Eldad Zack <[email protected]>
--- lib/vsprintf.c | 8 ++++++++ 1 files changed, 8 insertions(+), 0 deletions(-)
lib/vsprintf.c +8 -0
@@ -38,6 +38,8 @@* @cp: The start of the string * @endp: A pointer to the end of the parsed string will be placed here * @base: The number base to use +* +* This function is obsolete. Please use kstrtoull instead. */ unsigned long long simple_strtoull (const char *cp,char **endp,unsigned int base) {
@@ -61,6 +63,8 @@ EXPORT_SYMBOL(simple_strtoull);* @cp: The start of the string * @endp: A pointer to the end of the parsed string will be placed here * @base: The number base to use +* +* This function is obsolete. Please use kstrtoul instead. */ unsigned long simple_strtoul (const char *cp,char **endp,unsigned int base) {
@@ -73,6 +77,8 @@ EXPORT_SYMBOL(simple_strtoul);* @cp: The start of the string * @endp: A pointer to the end of the parsed string will be placed here * @base: The number base to use +* +* This function is obsolete. Please use kstrtol instead. */ long simple_strtol (const char *cp,char **endp,unsigned int base) {
@@ -88,6 +94,8 @@ EXPORT_SYMBOL(simple_strtol);* @cp: The start of the string * @endp: A pointer to the end of the parsed string will be placed here * @base: The number base to use +* +* This function is obsolete. Please use kstrtoll instead. */ long long simple_strtoll (const char *cp,char **endp,unsigned int base) {
Signature · 1 line
1.7.8.6