strcat.3: Add a program that shows the performance characteristics of strcat()

In honor of Joel Spolksy's visit to Munich, let's start educating
Schlemiel The Painter.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man3/strcat.3

@@ -179,6 +179,51 @@ is not present in glibc and is not standardized by POSIX,
 but is available on Linux via the
 .IR libbsd
 library.
+.\"
+.SH EXAMPLE
+Because
+.BR strcat ()
+and
+.BR strncat ()
+must find the null byte that terminates the string
+.I dest
+using a search that starts at the beginning of the string,
+the execution time of these functions
+scales according to the length of the string
+.IR dest .
+This can be demonstrated by running the program below.
+(If the goal is to concatenate many strings to one target,
+then manually copying the bytes from each source string
+while maintaining a pointer to the end of the target string
+will provide better performance.)
+.\"
+.SS Program source
+\&
+.nf
+#include <string.h>
+#include <time.h>
+#include <stdio.h>
+
+int
+main(int argc, char *argv[])
+{
+#define LIM 4000000
+    int j;
+    char p[LIM];
+    time_t base;
+     
+    base = time(NULL);
+    p[0] = \(aq\\0\(aq;
+
+    for (j = 0; j < LIM; j++) {
+        if ((j % 10000) == 0)
+            printf("%d %ld\\n", j, (long) (time(NULL) \- base));
+        strcat(p, "a");
+    }
+}
+.fi
+.BR 
+.\"
 .SH SEE ALSO
 .BR bcopy (3),
 .BR memccpy (3),