add examples

src/lib/libc/string/strcat.3

@@ -33,7 +33,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$OpenBSD: strcat.3,v 1.4 1998/11/28 14:51:34 espie Exp $
+.\"	$OpenBSD: strcat.3,v 1.5 1999/03/06 23:41:13 millert Exp $
 .\"
 .Dd July 8, 1997
 .Dt STRCAT 3
@@ -80,6 +80,45 @@ and
 functions
 return the pointer
 .Fa s .
+.Sh EXAMPLES
+The following appends
+.Dq Li abc
+to
+.Dq Li 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 .
+.Bd -literal -offset indent
+char buf[BUFSIZ];
+char *input, *suffix;
+
+(void)strncpy(buf, input, 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
+.Dq Li input
+to
+.Dq Li buf
+as will
+fit.  It then appends as many characters from suffix as will fit (or none
+if there is no space).  For operations like this, the
+.Xr strlcpy 3
+and
+.Xr strlcat 3
+functions are a better choice, as shown below.
+.Bd -literal -offset indent
+(void)strlcpy(buf, input, sizeof(buf));
+(void)strlcat(buf, suffix, sizeof(buf));
+.Ed
 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,