From b2f0984e042f0d21216f062bca7d4dc5f519f07c Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Tue, 21 Jun 2016 12:17:27 +0200
Subject: [PATCH] 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 | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/man3/strcat.3 b/man3/strcat.3
index 77d5488f9..bc1dd12c0 100644
--- a/man3/strcat.3
+++ b/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),