diff options
| -rw-r--r-- | lib/libc/string/strlcpy.3 | 128 |
1 files changed, 58 insertions, 70 deletions
diff --git a/lib/libc/string/strlcpy.3 b/lib/libc/string/strlcpy.3 index ead54ec4388..e04284d5c3d 100644 --- a/lib/libc/string/strlcpy.3 +++ b/lib/libc/string/strlcpy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: strlcpy.3,v 1.20 2011/07/25 00:38:53 schwarze Exp $ +.\" $OpenBSD: strlcpy.3,v 1.21 2012/04/02 17:33:11 deraadt Exp $ .\" .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com> .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 25 2011 $ +.Dd $Mdocdate: April 2 2012 $ .Dt STRLCPY 3 .Os .Sh NAME @@ -24,72 +24,79 @@ .Sh SYNOPSIS .Fd #include <string.h> .Ft size_t -.Fn strlcpy "char *dst" "const char *src" "size_t size" +.Fn strlcpy "char *dst" "const char *src" "size_t dstsize" .Ft size_t -.Fn strlcat "char *dst" "const char *src" "size_t size" +.Fn strlcat "char *dst" "const char *src" "size_t dstsize" .Sh DESCRIPTION The .Fn strlcpy and .Fn strlcat -functions copy and concatenate strings respectively. -They are designed -to be safer, more consistent, and less error prone replacements for +functions copy and concatenate strings with the +same input parameters and output result as +.Xr snprintf 3 . +They are designed to be safer, more consistent, and less error +prone replacements for the easily misused functions .Xr strncpy 3 and .Xr strncat 3 . -Unlike those functions, -.Fn strlcpy -and -.Fn strlcat -take the full size of the buffer (not just the length) and guarantee to -NUL-terminate the result (as long as -.Fa size -is larger than 0 or, in the case of -.Fn strlcat , -as long as there is at least one byte free in -.Fa dst ) . -Note that a byte for the NUL should be included in -.Fa size . -Also note that +.Pp .Fn strlcpy and .Fn strlcat -only operate on true -.Dq C -strings. -This means that for -.Fn strlcpy -.Fa src -must be NUL-terminated and for -.Fn strlcat -both -.Fa src -and -.Fa dst -must be NUL-terminated. +take the full size of the destination buffer and guarantee +NUL-termination if there is room. +Note that room for the NUL should be included in +.Fa dstsize . .Pp -The .Fn strlcpy -function copies up to -.Fa size -- 1 characters from the NUL-terminated string +copies up to +.Fa dstsize +\- 1 characters from the string .Fa src to .Fa dst , -NUL-terminating the result. +NUL-terminating the result if +.Fa dstsize +is not 0. .Pp -The .Fn strlcat -function appends the NUL-terminated string +appends string .Fa src to the end of .Fa dst . It will append at most -.Fa size -- strlen(dst) - 1 bytes, NUL-terminating the result. +.Fa dstsize +\- strlen(dst) \- 1 characters. +It will then NUL-terminate, unless +.Fa dstsize +is 0 or the original +.Fa dst +string was longer than +.Fa dstsize +(in practice this should not happen +as it means that either +.Fa dstsize +is incorrect or that +.Fa dst +is not a proper string). .Sh RETURN VALUES -The +Besides quibbles over the return type +.Pf ( Va size_t +versus +.Va int ) +and signal handler safety +.Xr ( snprintf 3 +is not entirely safe on some systems), the +following two are equivalent: +.Bd -literal -offset indent +n = strlcpy(dst, src, len); +n = snprintf(dst, len, "%s", src); +.Ed +.Pp +Like +.Xr snprintf 3 , +the .Fn strlcpy and .Fn strlcat @@ -105,29 +112,12 @@ that means the initial length of plus the length of .Fa src . -While this may seem somewhat confusing, it was done to make -truncation detection simple. .Pp -Note, however, that if -.Fn strlcat -traverses -.Fa size -characters without finding a NUL, the length of the string is considered -to be -.Fa size -and the destination string will not be NUL-terminated (since there was -no space for the NUL). -This keeps -.Fn strlcat -from running off the end of a string. -In practice this should not happen (as it means that either -.Fa size -is incorrect or that -.Fa dst -is not a proper -.Dq C -string). -The check exists to prevent potential security problems in incorrect code. +If the return value is +.Cm >= +.Va dstsize , +the output string has been truncated. +It is the caller's responsibility to handle this. .Sh EXAMPLES The following code fragment illustrates the simple case: .Bd -literal -offset indent @@ -179,16 +169,14 @@ As a matter of fact, the first version of this manual page got it wrong. .Xr strncpy 3 , .Xr wcslcpy 3 .Sh HISTORY -The .Fn strlcpy and .Fn strlcat -functions first appeared in +first appeared in .Ox 2.4 . .Sh AUTHORS -The .Fn strlcpy and .Fn strlcat -functions were created by +were created by .An Todd C. Miller Aq Todd.Miller@courtesan.com . |