Re: [PATCH 2/2] kernel-doc: core-api: Include string.h into core-api

Kees Cook
2019-07-23T21:28:19Z

On Mon, Jul 22, 2019 at 05:38:16PM -0700, Joe Perches wrote:
> core-api should show all the various string functions including the
> newly added stracpy and stracpy_pad.
>
> Miscellanea:
>
> o Update the Returns: value for strscpy
> o fix a defect with %NUL)
>
> Signed-off-by: Joe Perches <joe@perches.com>

Reviewed-by: Kees Cook <keescook@chromium.org>

-Kees

> ---
> Documentation/core-api/kernel-api.rst | 3 +++
> include/linux/string.h | 5 +++--
> lib/string.c | 10 ++++++----
> 3 files changed, 12 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> index 08af5caf036d..f77de49b1d51 100644
> --- a/Documentation/core-api/kernel-api.rst
> +++ b/Documentation/core-api/kernel-api.rst
> @@ -42,6 +42,9 @@ String Manipulation
> .. kernel-doc:: lib/string.c
> :export:
>
> +.. kernel-doc:: include/linux/string.h
> + :internal:
> +
> .. kernel-doc:: mm/util.c
> :functions: kstrdup kstrdup_const kstrndup kmemdup kmemdup_nul memdup_user
> vmemdup_user strndup_user memdup_user_nul
> diff --git a/include/linux/string.h b/include/linux/string.h
> index f80b0973f0e5..329188fffc11 100644
> --- a/include/linux/string.h
> +++ b/include/linux/string.h
> @@ -515,8 +515,9 @@ static inline void memcpy_and_pad(void *dest, size_t dest_len,
> * But this can lead to bugs due to typos, or if prefix is a pointer
> * and not a constant. Instead use str_has_prefix().
> *
> - * Returns: 0 if @str does not start with @prefix
> - strlen(@prefix) if @str does start with @prefix
> + * Returns:
> + * * strlen(@prefix) if @str starts with @prefix
> + * * 0 if @str does not start with @prefix
> */
> static __always_inline size_t str_has_prefix(const char *str, const char *prefix)
> {
> diff --git a/lib/string.c b/lib/string.c
> index 461fb620f85f..53582b6dce2a 100644
> --- a/lib/string.c
> +++ b/lib/string.c
> @@ -173,8 +173,9 @@ EXPORT_SYMBOL(strlcpy);
> * doesn't unnecessarily force the tail of the destination buffer to be
> * zeroed. If zeroing is desired please use strscpy_pad().
> *
> - * Return: The number of characters copied (not including the trailing
> - * %NUL) or -E2BIG if the destination buffer wasn't big enough.
> + * Returns:
> + * * The number of characters copied (not including the trailing %NUL)
> + * * -E2BIG if count is 0.
> */
> ssize_t strscpy(char *dest, const char *src, size_t count)
> {
> @@ -253,8 +254,9 @@ EXPORT_SYMBOL(strscpy);
> * For full explanation of why you may want to consider using the
> * 'strscpy' functions please see the function docstring for strscpy().
> *
> - * Return: The number of characters copied (not including the trailing
> - * %NUL) or -E2BIG if the destination buffer wasn't big enough.
> + * Returns:
> + * * The number of characters copied (not including the trailing %NUL)
> + * * -E2BIG if count is 0.
> */
> ssize_t strscpy_pad(char *dest, const char *src, size_t count)
> {
> --
> 2.15.0
>

--
Kees Cook