checkpatch: Added warnings in favor of strscpy().
Subsystems (3)
PATCH 1/1 checkpatch: Added warnings in favor of strscpy().
Added warnings in checkpatch.pl script to :
1. Deprecate strcpy() in favor of strscpy().
2. Deprecate strlcpy() in favor of strscpy().
3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
--- scripts/checkpatch.pl | 3 +++ 1 file changed, 3 insertions(+)
scripts/checkpatch.pl +3 -0
@@ -595,6 +595,9 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy or strscpy_pad", ); #Create a search pattern for all these strings to speed up a loop below
--
2.7.4
Quoted 7 lines · Nitin Gote
Added warnings in checkpatch.pl script to :
1. Deprecate
strcpy()in favor ofstrscpy().
2. Deprecatestrlcpy()in favor ofstrscpy().
3. Deprecatestrncpy()in favor ofstrscpy()orstrscpy_pad().Signed-off-by Nitin Gote <[email protected]>
Excellent, yes. Can you also add a bit to the strncpy() section in Documentation/process/deprecated.rst so that all three cases of strncpy() are explained:
- strncpy() into NUL-terminated target should use strscpy()
- strncpy() into NUL-terminated target needing trailing NUL: strscpy_pad()
- strncpy() into non-NUL-terminated target should have target marked with __nonstring.
(and probably mention the __nonstring case in checkpatch too)
-Kees
Quoted 21 lines
--- scripts/checkpatch.pl | 3 +++ 1 file changed, 3 insertions(+)scripts/checkpatch.pl +3
-1@@ -595,6 +595,9 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy or strscpy_pad", ); #Create a search pattern for all these strings to speed up a loop below --2.7.4
Signature · 1 line
Kees Cook
Hi Kees,
As per my understanding, I have updated strncpy() section in Documentation/process/deprecated.rst for strscpy_pad() case. Other two cases of strncpy() are already explained.
Also updated checkpatch for __nonstring case.
Could you please give your inputs on below diff changes ? If this looks good, I will send the patch.
Diff changes :
Documentation/process/deprecated.rst +3 -0
@@ -102,6 +102,9 @@ still be used, but destinations should be marked with the `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ attribute to avoid future compiler warnings. +If a caller is using NUL-terminated strings, and destination needing +trailing NUL, then the safe replace is :c:func:`strscpy_pad()`. + strlcpy() --------- :c:func:`strlcpy` reads the entire source buffer first, possibly exceeding
scripts/checkpatch.pl +4 -0
@@ -595,6 +595,10 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy, strscpy_pad Or for non-NUL-terminated strings, + strncpy() can still be used, but destinations should be marked with the __nonstring", );
Thanks and Regards,
Nitin Gote
-----Original Message-----
From: Kees Cook [mailto:[email protected]]
Sent: Friday, June 28, 2019 8:16 PM
To: Gote, Nitin R <[email protected]>
Cc: [email protected]; [email protected]
Subject: Re: [PATCH] checkpatch: Added warnings in favor of strscpy().
Quoted 7 lines · Nitin Gote
Added warnings in checkpatch.pl script to :
1. Deprecate
strcpy()in favor ofstrscpy().
2. Deprecatestrlcpy()in favor ofstrscpy().
3. Deprecatestrncpy()in favor ofstrscpy()orstrscpy_pad().Signed-off-by Nitin Gote <[email protected]>
Excellent, yes. Can you also add a bit to the strncpy() section in Documentation/process/deprecated.rst so that all three cases of strncpy() are explained:
- strncpy() into NUL-terminated target should use strscpy()
- strncpy() into NUL-terminated target needing trailing NUL: strscpy_pad()
- strncpy() into non-NUL-terminated target should have target marked with __nonstring.
(and probably mention the __nonstring case in checkpatch too)
-Kees
Quoted 18 lines
--- scripts/checkpatch.pl | 3 +++ 1 file changed, 3 insertions(+)scripts/checkpatch.pl index renamed from scripts/checkpatch.pl +0
-0342c7c7..bb0fa11 100755
scripts/checkpatch.pl +3
-0@@ -595,6 +595,9 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy or strscpy_pad", ); #Create a search pattern for all these strings to speed up a loop
Quoted 4 lines
below
--
2.7.4
--
Kees Cook
Quoted 15 lines · Nitin R
Hi Kees,
As per my understanding, I have updated
strncpy()section inDocumentation/process/deprecated.rstforstrscpy_pad()case. Other two cases ofstrncpy()are already explained.Also updated checkpatch for
__nonstringcase.Could you please give your inputs on below diff changes ? If this looks good, I will send the patch.
Diff changes :
Documentation/process/deprecated.rst +0
-0
Documentation/process/deprecated.rst still be used, but destinations should be marked with the `__nonstring · line 106
Quoted 5 lines
Documentation/process/deprecated.rst +2
-0@@ -102,6 +102,9 @@ still be used, but destinations should be marked with the `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ attribute to avoid future compiler warnings. +If a caller is using NUL-terminated strings, and destination needing +trailing NUL, then the safe replace is :c:func:`strscpy_pad()`.
I'd move this above the __nonstring discussion and remove the memset mention. How about doing this?
Documentation/process/deprecated.rst +3 -3
@@ -93,9 +93,9 @@ will be NUL terminated. This can lead to various linear read overflows and other misbehavior due to the missing termination. It also NUL-pads the destination buffer if the source contents are shorter than the destination buffer size, which may be a needless performance penalty for callers using -only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. -(Users of :c:func:`strscpy` still needing NUL-padding will need an -explicit :c:func:`memset` added.) +only NUL-terminated strings. In this case, the safe replacement is +:c:func:`strscpy`. If, however, the destination buffer still needs +NUL-padding, the safe replacement is :c:func:`strscpy_pad`. If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can still be used, but destinations should be marked with the `__nonstring
Quoted 9 lines
Documentation/process/deprecated.rst +1
-0+ strlcpy() --------- :c:func:`strlcpy` reads the entire source buffer first, possibly exceedingscripts/checkpatch.pl +0
-0
scripts/checkpatch.pl our %deprecated_apis = ( · line 601
Quoted 7 lines
scripts/checkpatch.pl +4
-0@@ -595,6 +595,10 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy, strscpy_pad Or for non-NUL-terminated strings, + strncpy() can still be used, but destinations should be marked with the __nonstring",
I found the "Or" strange here; I think just "or" is fine.
-Kees
Quoted 57 lines
scripts/checkpatch.pl +0
-0); Thanks and Regards,Nitin Gote
-----Original Message-----
From: Kees Cook [mailto:[email protected]]
Sent: Friday, June 28, 2019 8:16 PM
To: Gote, Nitin R <[email protected]>
Cc: [email protected]; [email protected]
Subject: Re: [PATCH] checkpatch: Added warnings in favor ofstrscpy().Quoted 7 lines · Nitin Gote
Added warnings in checkpatch.pl script to :
1. Deprecate
strcpy()in favor ofstrscpy().
2. Deprecatestrlcpy()in favor ofstrscpy().
3. Deprecatestrncpy()in favor ofstrscpy()orstrscpy_pad().Signed-off-by Nitin Gote <[email protected]>Excellent, yes. Can you also add a bit to the
strncpy()section inDocumentation/process/deprecated.rstso that all three cases ofstrncpy()are explained:-
strncpy()into NUL-terminated target should usestrscpy()
-strncpy()into NUL-terminated target needing trailing NUL:strscpy_pad()
-strncpy()into non-NUL-terminated target should have target marked with__nonstring.(and probably mention the
__nonstringcase in checkpatch too)-Kees
Quoted 18 lines
--- scripts/checkpatch.pl | 3 +++ 1 file changed, 3 insertions(+)scripts/checkpatch.pl index renamed from scripts/checkpatch.pl +0
-0342c7c7..bb0fa11 100755
scripts/checkpatch.pl +3
-0@@ -595,6 +595,9 @@ our %deprecated_apis = ( "rcu_barrier_sched" => "rcu_barrier", "get_state_synchronize_sched" => "get_state_synchronize_rcu", "cond_synchronize_sched" => "cond_synchronize_rcu", + "strcpy" => "strscpy", + "strlcpy" => "strscpy", + "strncpy" => "strscpy or strscpy_pad", ); #Create a search pattern for all these strings to speed up a loopQuoted 4 lines
below
--
2.7.4--
Kees Cook
Signature · 1 line
Kees Cook
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().
This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
Regards,
Stephen
Quoted 11 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded strcpy() macros in string.h?
Signature · 1 line
Kees Cook
Quoted 10 lines · Kees Cook
Quoted 9 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Quoted 6 lines
Quoted 3 lines
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded
strcpy()macros instring.h?
The latter; in my mind the point is to simplify the thought process for developers, so strscpy should be the “obvious” choice in all cases, even when dealing with constant strings in hot paths. Something like
__FORTIFY_INLINE ssize_t strscpy(char *dest, const char *src, size_t count)
{
size_t dest_size = __builtin_object_size(dest, 0);
size_t src_size = __builtin_object_size(src, 0);
if (__builtin_constant_p(count) &&
__builtin_constant_p(src_size) &&
__builtin_constant_p(dest_size) &&
src_size <= count &&
src_size <= dest_size &&
src[src_size - 1] == '\0') {
strcpy(dest, src);
return src_size - 1;
} else {
return __strscpy(dest, src, count);
}
}with the current strscpy renamed to __strscpy. I imagine it’s not necessary to tie this to FORTIFY — __OPTIMIZE__ should be sufficient, shouldn’t it? Although building on top of the fortified strcpy is reassuring, and I might be missing something. I’m also not sure how to deal with the backing strscpy:
weak symbol, or something else... At least there aren’t (yet) any arch-specific implementations of strscpy to deal with, but obviously they’d still need to be supportable.
In my tests, this all gets optimised away, and we end up with code such as
strscpy(raead.type, "aead", sizeof(raead.type));
being compiled down to
movl $1684104545, 4(%rsp)
on x86-64, and non-constant code being compiled down to a direct __strscpy call.
Regards,
Stephen
Quoted 40 lines · Stephen Kitt
Quoted 11 lines · Kees Cook
Quoted 10 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Quoted 6 lines
Quoted 3 lines
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded
strcpy()macros instring.h?The latter; in my mind the point is to simplify the thought process for developers, so strscpy should be the “obvious” choice in all cases, even when dealing with constant strings in hot paths. Something like
__FORTIFY_INLINEssize_tstrscpy(char *dest, const char *src, size_t count){ size_t dest_size = __builtin_object_size(dest, 0); size_t src_size = __builtin_object_size(src, 0); if (__builtin_constant_p(count) && __builtin_constant_p(src_size) && __builtin_constant_p(dest_size) && src_size <= count && src_size <= dest_size && src[src_size - 1] == '\0') { strcpy(dest, src); return src_size - 1; } else { return __strscpy(dest, src, count); } }
Quoted 7 lines
with the current strscpy renamed to
__strscpy. I imagine it’s not necessary to tie this to FORTIFY —__OPTIMIZE__should be sufficient, shouldn’t it? Although building on top of the fortified strcpy is reassuring, and I might be missing something. I’m also not sure how to deal with the backing
strscpy: weak symbol, or something else... At least there aren’t (yet) any arch-specific implementations of strscpy to deal with, but obviously they’d still need to be supportable.
And there are at least two baked-in assumptions here: src really is a constant string (so the if should only trigger then), to avoid TOCTTOU races, and there is only a single null byte at the end of src.
Quoted 14 lines
In my tests, this all gets optimised away, and we end up with code such as
strscpy(raead.type, "aead", sizeof(raead.type));being compiled down to
movl $1684104545, 4(%rsp)on x86-64, and non-constant code being compiled down to a direct
__strscpycall.Regards,
Stephen
Quoted 49 lines · Stephen Kitt
Quoted 10 lines · Kees Cook
Quoted 9 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Quoted 6 lines
Quoted 3 lines
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded
strcpy()macros instring.h?The latter; in my mind the point is to simplify the thought process for developers, so strscpy should be the “obvious” choice in all cases, even when dealing with constant strings in hot paths. Something like
__FORTIFY_INLINEssize_tstrscpy(char *dest, const char *src, size_t count){ size_t dest_size = __builtin_object_size(dest, 0); size_t src_size = __builtin_object_size(src, 0); if (__builtin_constant_p(count) && __builtin_constant_p(src_size) && __builtin_constant_p(dest_size) && src_size <= count && src_size <= dest_size && src[src_size - 1] == '\0') { strcpy(dest, src); return src_size - 1; } else { return __strscpy(dest, src, count); } }with the current strscpy renamed to
__strscpy. I imagine it’s not necessary to tie this to FORTIFY —__OPTIMIZE__should be sufficient, shouldn’t it? Although building on top of the fortified strcpy is reassuring, and I might be missing something. I’m also not sure how to deal with the backing strscpy:
weak symbol, or something else... At least there aren’t (yet) any arch-specific implementations of strscpy to deal with, but obviously they’d still need to be supportable.In my tests, this all gets optimised away, and we end up with code such as
Quoted 8 lines
strscpy(raead.type, "aead", sizeof(raead.type));being compiled down to
movl $1684104545, 4(%rsp)on x86-64, and non-constant code being compiled down to a direct
__strscpycall.
Thanks for the details! Yeah, that seems nice. I wonder if there is a sensible way to combine these also with the stracpy*() proposal[1], so the call in your example above could just be:
stracpy(raead.type, "aead");
(It seems both proposals together would have the correct result...)
[1] https://lkml.kernel.org/r/201907221031.8B87A9DE@keescook
Signature · 1 line
Kees Cook
Joe Perches
maintainerQuoted 63 lines · Kees Cook
Quoted 49 lines · Stephen Kitt
Quoted 10 lines · Kees Cook
Quoted 9 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Quoted 6 lines
Quoted 3 lines
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded
strcpy()macros instring.h?The latter; in my mind the point is to simplify the thought process for developers, so strscpy should be the “obvious” choice in all cases, even when dealing with constant strings in hot paths. Something like
__FORTIFY_INLINEssize_tstrscpy(char *dest, const char *src, size_t count){ size_t dest_size = __builtin_object_size(dest, 0); size_t src_size = __builtin_object_size(src, 0); if (__builtin_constant_p(count) && __builtin_constant_p(src_size) && __builtin_constant_p(dest_size) && src_size <= count && src_size <= dest_size && src[src_size - 1] == '\0') { strcpy(dest, src); return src_size - 1; } else { return __strscpy(dest, src, count); } }with the current strscpy renamed to
__strscpy. I imagine it’s not necessary to tie this to FORTIFY —__OPTIMIZE__should be sufficient, shouldn’t it? Although building on top of the fortified strcpy is reassuring, and I might be missing something. I’m also not sure how to deal with the backing strscpy:
weak symbol, or something else... At least there aren’t (yet) any arch-specific implementations of strscpy to deal with, but obviously they’d still need to be supportable.In my tests, this all gets optimised away, and we end up with code such as
Quoted 8 lines
strscpy(raead.type, "aead", sizeof(raead.type));being compiled down to
movl $1684104545, 4(%rsp)on x86-64, and non-constant code being compiled down to a direct
__strscpycall.Thanks for the details! Yeah, that seems nice. I wonder if there is a sensible way to combine these also with the stracpy*() proposal[1], so the call in your example above could just be:
Quoted 5 lines
stracpy(raead.type, "aead");(It seems both proposals together would have the correct result...)
[1] https://lkml.kernel.org/r/201907221031.8B87A9DE@keescook
Easy enough to do.
Quoted 68 lines · Joe Perches
Quoted 67 lines · Kees Cook
Quoted 53 lines · Stephen Kitt
Quoted 11 lines · Kees Cook
Quoted 10 lines · Stephen Kitt
Quoted 1 line · Nitin Gote
1. Deprecate
strcpy()in favor ofstrscpy().This isn’t a comment “against” this patch, but something I’ve been wondering recently and which raises a question about how to handle strcpy’s deprecation in particular. There is still one scenario where strcpy is useful: when GCC replaces it with its builtin, inline version...
Quoted 7 lines
Quoted 4 lines
Would it be worth introducing a macro for strcpy-from-constant-string, which would check that GCC’s builtin is being used (when building with GCC), and fall back to strscpy otherwise?
How would you suggest it operate? A separate API, or something like the existing overloaded
strcpy()macros instring.h?The latter; in my mind the point is to simplify the thought process for developers, so strscpy should be the “obvious” choice in all cases, even when dealing with constant strings in hot paths. Something like
__FORTIFY_INLINEssize_tstrscpy(char *dest, const char *src,size_tcount) { size_t dest_size = __builtin_object_size(dest, 0); size_t src_size = __builtin_object_size(src, 0); if (__builtin_constant_p(count) && __builtin_constant_p(src_size) && __builtin_constant_p(dest_size) && src_size <= count && src_size <= dest_size && src[src_size - 1] == '\0') { strcpy(dest, src); return src_size - 1; } else { return __strscpy(dest, src, count); } }with the current strscpy renamed to
__strscpy. I imagine it’s not necessary to tie this to FORTIFY —__OPTIMIZE__should be sufficient, shouldn’t it? Although building on top of the fortified strcpy is reassuring, and I might be missing something. I’m also not sure how to deal with the backing strscpy: weak symbol, or something else... At least there aren’t (yet) any arch-specific implementations of strscpy to deal with, but obviously they’d still need to be supportable.In my tests, this all gets optimised away, and we end up with code such as
Quoted 8 lines
strscpy(raead.type, "aead", sizeof(raead.type));being compiled down to
movl $1684104545, 4(%rsp)on x86-64, and non-constant code being compiled down to a direct
__strscpycall.Thanks for the details! Yeah, that seems nice. I wonder if there is a sensible way to combine these also with the stracpy*() proposal[1], so the call in your example above could just be:
Quoted 7 lines
Quoted 5 lines
stracpy(raead.type, "aead");(It seems both proposals together would have the correct result...)
[1] https://lkml.kernel.org/r/201907221031.8B87A9DE@keescook
Easy enough to do.
How about you submit your current patch set, and I follow up with the above adapted to stracpy?
Regards,
Stephen
Joe Perches
maintainerQuoted 2 lines · Stephen Kitt
How about you submit your current patch set, and I follow up with the above adapted to stracpy?
OK, I will shortly after I figure out how to add kernel-doc for stracpy/stracpy_pad to lib/string.c.
It doesn't seem appropriate to add the kernel-doc to string.h as it would be separated from the others in string.c
Anyone got a clue here? Jonathan?
Jonathan Corbet
maintainerQuoted 11 lines · On Mon, 22 Jul 2019 14:50:09 -0700 Joe Perches <[email protected]> wrote:
Quoted 2 lines · Stephen Kitt
How about you submit your current patch set, and I follow up with the above adapted to stracpy?
OK, I will shortly after I figure out how to add kernel-doc for stracpy/stracpy_pad to
lib/string.c.It doesn't seem appropriate to add the kernel-doc to
string.has it would be separated from the others instring.cAnyone got a clue here? Jonathan?
If the functions themselves are fully defined in the .h file, I'd just add the kerneldoc there as well. That's how it's usually done, and you want to keep the documentation and the prototypes together.
jon
Joe Perches
maintainerQuoted 10 lines · Jonathan Corbet
Quoted 7 lines · On Mon, 22 Jul 2019 14:50:09 -0700 Joe Perches <[email protected]> wrote:
Quoted 2 lines · Stephen Kitt
How about you submit your current patch set, and I follow up with the above adapted to stracpy?
OK, I will shortly after I figure out how to add kernel-doc for stracpy/stracpy_pad to
lib/string.c.
Quoted 8 lines
Quoted 4 lines
It doesn't seem appropriate to add the kernel-doc to
string.has it would be separated from the others instring.cAnyone got a clue here? Jonathan?
If the functions themselves are fully defined in the .h file, I'd just add the kerneldoc there as well. That's how it's usually done, and you want to keep the documentation and the prototypes together.
In this case, it's a macro and yes, the kernel-doc could easily be set around the macro in the .h, but my desire is to keep all the string function kernel-doc output together so it should be added to lib/string.c
Are you suggesting I move all the lib/string.c kernel-doc to include/linux/string.h ?
Jonathan Corbet
maintainerQuoted 11 lines · On Mon, 22 Jul 2019 15:24:33 -0700 Joe Perches <[email protected]> wrote:
Quoted 3 lines
If the functions themselves are fully defined in the .h file, I'd just add the kerneldoc there as well. That's how it's usually done, and you want to keep the documentation and the prototypes together.
In this case, it's a macro and yes, the kernel-doc could easily be set around the macro in the .h, but my desire is to keep all the string function kernel-doc output together so it should be added to
lib/string.cAre you suggesting I move all the
lib/string.ckernel-doc toinclude/linux/string.h?
If you want the *output* together, just put the kernel-doc directives together in the RST file that pulls it all in. Or am I missing something here?
Thanks,
jon
Joe Perches
maintainerQuoted 12 lines · Jonathan Corbet
Quoted 9 lines · On Mon, 22 Jul 2019 15:24:33 -0700 Joe Perches <[email protected]> wrote:
Quoted 3 lines
If the functions themselves are fully defined in the .h file, I'd just add the kerneldoc there as well. That's how it's usually done, and you want to keep the documentation and the prototypes together.
In this case, it's a macro and yes, the kernel-doc could easily be set around the macro in the .h, but my desire is to keep all the string function kernel-doc output together so it should be added to
lib/string.c
Quoted 6 lines
Quoted 2 lines
Are you suggesting I move all the
lib/string.ckernel-doc toinclude/linux/string.h?If you want the *output* together, just put the kernel-doc directives together in the RST file that pulls it all in. Or am I missing something here?
Nah, it's me.
I'm not particularly up to date on .rst file usage.
Thanks.
Joe Perches
maintainerQuoted 12 lines · Jonathan Corbet
Quoted 9 lines · On Mon, 22 Jul 2019 15:24:33 -0700 Joe Perches <[email protected]> wrote:
Quoted 3 lines
If the functions themselves are fully defined in the .h file, I'd just add the kerneldoc there as well. That's how it's usually done, and you want to keep the documentation and the prototypes together.
In this case, it's a macro and yes, the kernel-doc could easily be set around the macro in the .h, but my desire is to keep all the string function kernel-doc output together so it should be added to
lib/string.c
Quoted 6 lines
Quoted 2 lines
Are you suggesting I move all the
lib/string.ckernel-doc toinclude/linux/string.h?If you want the *output* together, just put the kernel-doc directives together in the RST file that pulls it all in. Or am I missing something here?
The negative of the kernel-doc separation of prototypes by .h and .c files is that the ordering of the functions in the .rst outout files doesn't make much logical sense.
stracpy is pretty far away from strscpy in the list of functions.