Browse Source

simplify the strlcpy/strlcat manual page substantially. do less

explaining of "what a C string is", and make it more clear that these
functiosn BEHAVE EXACTLY LIKE snprintf with "%s"!  (anyone who wants
to write a 'strlcpy considered harmful' paper should probably write a
'strlcpy and snprintf considered harmful' paper instead).
note to those from other projects reading this commit message: It would
be very good if this new manual was picked up in your project.
ok jmc millert krw
OPENBSD_5_2
deraadt 12 years ago
parent
commit
21ec91c765
1 changed files with 58 additions and 70 deletions
  1. +58
    -70
      src/lib/libc/string/strlcpy.3

+ 58
- 70
src/lib/libc/string/strlcpy.3 View File

@ -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> .\" 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 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" .\"
.Dd $Mdocdate: July 25 2011 $
.Dd $Mdocdate: April 2 2012 $
.Dt STRLCPY 3 .Dt STRLCPY 3
.Os .Os
.Sh NAME .Sh NAME
@ -24,72 +24,79 @@
.Sh SYNOPSIS .Sh SYNOPSIS
.Fd #include <string.h> .Fd #include <string.h>
.Ft size_t .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 .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 .Sh DESCRIPTION
The The
.Fn strlcpy .Fn strlcpy
and and
.Fn strlcat .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 .Xr strncpy 3
and and
.Xr strncat 3 . .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 .Fn strlcpy
and and
.Fn strlcat .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 .Pp
The
.Fn strlcpy .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 .Fa src
to to
.Fa dst , .Fa dst ,
NUL-terminating the result.
NUL-terminating the result if
.Fa dstsize
is not 0.
.Pp .Pp
The
.Fn strlcat .Fn strlcat
function appends the NUL-terminated string
appends string
.Fa src .Fa src
to the end of to the end of
.Fa dst . .Fa dst .
It will append at most 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 .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 .Fn strlcpy
and and
.Fn strlcat .Fn strlcat
@ -105,29 +112,12 @@ that means the initial length of
plus plus
the length of the length of
.Fa src . .Fa src .
While this may seem somewhat confusing, it was done to make
truncation detection simple.
.Pp .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 .Sh EXAMPLES
The following code fragment illustrates the simple case: The following code fragment illustrates the simple case:
.Bd -literal -offset indent .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 strncpy 3 ,
.Xr wcslcpy 3 .Xr wcslcpy 3
.Sh HISTORY .Sh HISTORY
The
.Fn strlcpy .Fn strlcpy
and and
.Fn strlcat .Fn strlcat
functions first appeared in
first appeared in
.Ox 2.4 . .Ox 2.4 .
.Sh AUTHORS .Sh AUTHORS
The
.Fn strlcpy .Fn strlcpy
and and
.Fn strlcat .Fn strlcat
functions were created by
were created by
.An Todd C. Miller Aq Todd.Miller@courtesan.com . .An Todd C. Miller Aq Todd.Miller@courtesan.com .

Loading…
Cancel
Save