non-dangerous use functions is difficult.
ok guenther
-.\" $OpenBSD: strcat.3,v 1.16 2013/12/19 20:52:37 millert Exp $
+.\" $OpenBSD: strcat.3,v 1.17 2014/04/19 11:30:40 deraadt Exp $
.\"
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd $Mdocdate: December 19 2013 $
+.Dd $Mdocdate: April 19 2014 $
.Dt STRCAT 3
.Os
.Sh NAME
.Nm strcat
-.Nd concatenate two strings
+.Nd concatenate two strings without bounds checking
.Sh SYNOPSIS
.In string.h
.Ft char *
.Fa s ,
then adds a terminating
.Ql \e0 .
-The string
-.Fa s
-must have sufficient space to hold the result.
+.Pp
+No bounds checking is performed.
+If the buffer
+.Fa dst
+is not large enough to hold the result,
+subsequent memory will be damaged.
.Sh RETURN VALUES
The
.Fn strcat
function return the pointer
.Fa s .
.Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcpy 3 ,
.Xr strlcpy 3 ,
-.Xr strncat 3 ,
.Xr wcscat 3 ,
.Xr wcslcpy 3
.Sh STANDARDS
-.\" $OpenBSD: strcpy.3,v 1.20 2013/12/19 20:52:37 millert Exp $
+.\" $OpenBSD: strcpy.3,v 1.21 2014/04/19 11:30:40 deraadt Exp $
.\"
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd $Mdocdate: December 19 2013 $
+.Dd $Mdocdate: April 19 2014 $
.Dt STRCPY 3
.Os
.Sh NAME
.Nm strcpy
-.Nd copy a string
+.Nd copy a string without bounds checking
.Sh SYNOPSIS
.In string.h
.Ft char *
.Fn strcpy
function copies the string
.Fa src
-to
-.Fa dst
(including the terminating
.Ql \e0
-character).
-The string
+character) to the buffer
+.Fa dst .
+.Pp
+No bounds checking is performed.
+If the buffer
.Fa dst
-must be at least as large as
-.Fa src
-to hold the result.
+is not large enough to hold the result,
+subsequent memory will be damaged.
.Pp
If the
.Fa src
-and
+string is inside the
.Fa dst
-strings overlap, the behavior is undefined.
+buffer, the behavior is undefined.
.Sh RETURN VALUES
The
.Fn strcpy
function returns
.Fa dst .
.Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcat 3 ,
.Xr strlcpy 3 ,
-.Xr strncpy 3 ,
.Xr wcscpy 3 ,
.Xr wcslcpy 3
.Sh STANDARDS
The
.Fn strcpy
-and
-.Fn strncpy
-functions conform to
+function conforms to
.St -ansiC .
.Sh HISTORY
The
-.\" $OpenBSD: strncat.3,v 1.2 2013/12/19 22:00:58 jmc Exp $
+.\" $OpenBSD: strncat.3,v 1.3 2014/04/19 11:30:40 deraadt Exp $
.\"
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd $Mdocdate: December 19 2013 $
+.Dd $Mdocdate: April 19 2014 $
.Dt STRNCAT 3
.Os
.Sh NAME
.Sh SYNOPSIS
.In string.h
.Ft char *
-.Fn strncat "char *s" "const char *append" "size_t count"
+.Fn strncat "char *dst" "const char *append" "size_t count"
.Sh DESCRIPTION
The
.Fn strncat
function appends not more than
.Fa count
-characters of the NUL-terminated string
+characters of the string
.Fa append
-to the end of the NUL-terminated string
-.Fa s .
+to the end of the string found in the buffer
+.Fa dst .
Space for the terminating
.Ql \e0
should not be included in
.Fa count .
-The string
-.Fa s
-must have sufficient space to hold the result.
+.Pp
+Bounds checking must be performed manually with great care.
+If the buffer
+.Fa dst
+is not large enough to hold the result,
+subsequent memory will be damaged.
.Sh RETURN VALUES
The
.Fn strncat
function returns the pointer
-.Fa s .
+.Fa dst .
.Sh EXAMPLES
-The following appends
-.Dq Li abc
-to
-.Va chararray :
-.Bd -literal -offset indent
-char *letters = "abcdefghi";
-
-(void)strncat(chararray, letters, 3);
-.Ed
-.Pp
The following example shows how to use
.Fn strncat
-safely in conjunction with
-.Xr strncpy 3 .
+in conjunction with
+.Xr strncpy 3 :
.Bd -literal -offset indent
char buf[BUFSIZ];
-char *input, *suffix;
+char *base, *suffix;
-(void)strncpy(buf, input, sizeof(buf) - 1);
+(void)strncpy(buf, base, sizeof(buf) - 1);
buf[sizeof(buf) - 1] = '\e0';
(void)strncat(buf, suffix, sizeof(buf) - 1 - strlen(buf));
.Ed
.Pp
The above will copy as many characters from
-.Va input
+.Va base
to
.Va buf
as will fit.
It then appends as many characters from
.Va suffix
-as will fit (or none
-if there is no space).
-For operations like this, the
+as will fit.
+If either
+.Va base
+or
+.Va suffix
+are too large, truncation will occur without detection.
+.Pp
+The above example shows dangerous coding patterns, including an
+inability to detect truncation.
+.Fn strncat
+and
+.Fn strncpy
+are dangerously easy to misuse.
+The
.Xr strlcpy 3
and
.Xr strlcat 3
-functions are a better choice, as shown below.
+functions are safer for this kind of operation:
+.Bd -literal -offset indent
+if (strlcpy(buf, base, sizeof(buf)) >= sizeof(buf) ||
+ strlcat(buf, suffix, sizeof(buf)) >= sizeof(buf))
+ goto toolong;
+
+.Ed
+or for greatest portability,
.Bd -literal -offset indent
-(void)strlcpy(buf, input, sizeof(buf));
-(void)strlcat(buf, suffix, sizeof(buf));
+if (snprintf(buf, sizeof(buf), "%s%s",
+ base, suffix) >= sizeof(buf))
+ goto toolong;
.Ed
+
.Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcat 3 ,
-.Xr strcpy 3 ,
.Xr strlcpy 3 ,
.Xr wcscat 3 ,
.Xr wcslcpy 3
.Sh STANDARDS
The
-.Fn strcat
-and
.Fn strncat
-functions conform to
+function conform to
.St -ansiC .
.Sh HISTORY
The
-.\" $OpenBSD: strncpy.3,v 1.1 2013/12/19 20:52:37 millert Exp $
+.\" $OpenBSD: strncpy.3,v 1.2 2014/04/19 11:30:40 deraadt Exp $
.\"
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd $Mdocdate: December 19 2013 $
+.Dd $Mdocdate: April 19 2014 $
.Dt STRNCPY 3
.Os
.Sh NAME
.Fa len
characters from the string
.Fa src
-to
+to the buffer
.Fa dst .
If
.Fa src
is less than
.Fa len
characters long,
-it appends
+it fills the remaining buffer with
.Ql \e0
-characters for the rest of
-.Fa len .
+characters.
If the length of
.Fa src
is greater than or equal to
.Em not
be NUL-terminated.
.Pp
+.Fn strncpy
+.Em only
+NUL terminates the destination string when the length of the source
+string is less than the length parameter.
+.Pp
If the
.Fa src
and
The following sets
.Va chararray
to
-.Dq abcdef
-and does
-.Em not
-NUL terminate
-.Va chararray
-because the length of the source string is greater than or equal to the
-length parameter.
-.Fn strncpy
-.Em only
-NUL terminates the destination string when the length of the source
-string is less than the length parameter.
+.Dq abcdef ,
+without a NUL-terminator:
.Bd -literal -offset indent
(void)strncpy(chararray, "abcdefgh", 6);
.Ed
.Pp
-The following copies as many characters from
+The following sequence copies as many characters from
.Va input
to
.Va buf
-as will fit and NUL terminates the result.
-Because
-.Fn strncpy
-does
-.Em not
-guarantee to NUL terminate the string itself, it must be done by hand.
+as will fit, and then NUL terminates the result by hand:
.Bd -literal -offset indent
char buf[BUFSIZ];
buf[sizeof(buf) - 1] = '\e0';
.Ed
.Pp
-Note that
-.Xr strlcpy 3
-is a better choice for this kind of operation.
-The equivalent using
+By now it is clear that
+.Nm strncpy
+is dangerously easy to misuse.
+The
.Xr strlcpy 3
-is simply:
+function is safer for this kind of operation:
.Bd -literal -offset indent
-(void)strlcpy(buf, input, sizeof(buf));
+if (strlcpy(buf, input, sizeof(buf)) >= sizeof(buf))
+ goto toolong;
.Ed
.Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcat 3 ,
.Xr strlcpy 3 ,
-.Xr strncat 3 ,
.Xr wcscpy 3 ,
.Xr wcslcpy 3
.Sh STANDARDS
projects / openbsd / commitdiff