Improve the discussion of strncat().

1 files changed, 44 insertions, 9 deletions

diff --git a/man3/strcat.3 b/man3/strcat.3
index f0791e13..775714d8 100644
--- a/man3/strcat.3
+++ b/man3/strcat.3
@@ -25,7 +25,9 @@
 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
 .\"     386BSD man pages
 .\" Modified Sat Jul 24 18:11:47 1993 by Rik Faith (faith@cs.unc.edu)
-.TH STRCAT 3  1993-04-11 "GNU" "Linux Programmer's Manual"
+.\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr>
+.\"     Improve discussion of strncat().
+.TH STRCAT 3  2007-06-15 "GNU" "Linux Programmer's Manual"
 .SH NAME
 strcat, strncat \- concatenate two strings
 .SH SYNOPSIS
@@ -40,24 +42,57 @@ strcat, strncat \- concatenate two strings
 The
 .BR strcat ()
 function appends the \fIsrc\fP string to the
-\fIdest\fP string overwriting the `\\0' character at the end of
-\fIdest\fP, and then adds a terminating `\\0' character.
+\fIdest\fP string, overwriting the null character (`\\0') at the end of
+\fIdest\fP, and then adds a terminating null character.
 The strings may not overlap, and the \fIdest\fP string must have
 enough space for the result.
 .PP
 The
 .BR strncat ()
-function is similar, except that it will use
-at most \fIn\fP characters from \fIsrc\fP.
-Since the result is always terminated with `\\0', at most \fIn\fP+1
-characters are written.
+function is similar, except that
+.IP * 3
+it will use at most \fIn\fP characters from \fIsrc\fP; and
+.IP *
+\fIsrc\fP does not need to be null terminated if it contains
+\fIn\fP or more characters.
+.PP
+As with
+.BR strcat (),
+the resulting string in \fIdest\fP is always null terminated.
+.PP
+If \fIsrc\fP contains \fIn\fP or more characters,
+.BR strcat ()
+writes \fIn+1\fP characters to \fIdest\fP (\fIn\fP
+from \fIsrc\fP plus the terminating null character).
+Therefore, the size of \fIdest\fP must be at least 
+\fIstrlen(dest)+n+1\fP.
+
+A simple implementation of
+.BR strncat () 
+might be:
+.in +0.25i
+.nf
+
+char*
+strncat(char *dest, const char *src, size_t n)
+{
+    size_t dest_len = strlen(dest);
+    int i;
+
+    for(i = 0 ; i < n && src[i] != '\0' ; i++)
+        dest[dest_len + i] = src[i];
+    dest[dest_len + i] = '\0';
+
+    return dest;
+}
+.fi
+.in
 .SH "RETURN VALUE"
 The
 .BR strcat ()
 and
 .BR strncat ()
-functions return a pointer
-to the resulting string \fIdest\fP.
+functions return a pointer to the resulting string \fIdest\fP.
 .SH "CONFORMING TO"
 SVr4, 4.3BSD, C89, C99.
 .SH "SEE ALSO"