From 40146e6a1204b3d4b369b341dd7dd9a99455ee04 Mon Sep 17 00:00:00 2001
From: Sascha Wildner <saw@online.de>
Date: Mon, 21 Feb 2011 21:38:54 +0100
Subject: [PATCH] rtld.1: Add an example on how to set up _rtld_functrace.

While here, put the function's prototype into the SYNOPSIS and add a
_rtld_functrace(3) MLINK.
---
 libexec/rtld-elf/Makefile |  1 +
 libexec/rtld-elf/rtld.1   | 48 +++++++++++++++++++++++++++++++--------
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/libexec/rtld-elf/Makefile b/libexec/rtld-elf/Makefile
index 07d28c114a..ffa8413999 100644
--- a/libexec/rtld-elf/Makefile
+++ b/libexec/rtld-elf/Makefile
@@ -14,6 +14,7 @@ INSTALLFLAGS+=	-fschg
 .endif
 MLINKS=		rtld.1 ld-elf.so.1.1
 MLINKS+=	rtld.1 ld-elf.so.2.1
+MLINKS+=	rtld.1 _rtld_functrace.3
 
 .if exists(${.CURDIR}/${MACHINE_ARCH}/Makefile.inc)
 .include "${.CURDIR}/${MACHINE_ARCH}/Makefile.inc"
diff --git a/libexec/rtld-elf/rtld.1 b/libexec/rtld-elf/rtld.1
index 4df89909d6..5c9a54513c 100644
--- a/libexec/rtld-elf/rtld.1
+++ b/libexec/rtld-elf/rtld.1
@@ -1,5 +1,4 @@
 .\" $FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.7 2002/01/10 17:51:28 ru Exp $
-.\" $DragonFly: src/libexec/rtld-elf/rtld.1,v 1.7 2008/05/02 02:05:05 swildner Exp $
 .\"
 .\" Copyright (c) 1995 Paul Kranenburg
 .\" All rights reserved.
@@ -29,14 +28,18 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 7, 2008
+.Dd February 21, 2011
 .Dt RTLD 1
 .Os
 .Sh NAME
 .Nm ld-elf.so.1 ,
 .Nm ld-elf.so.2 ,
-.Nm rtld
+.Nm rtld ,
+.Nm _rtld_functrace
 .Nd run-time link-editor
+.Sh SYNOPSIS
+.Ft int
+.Fn _rtld_functrace "const char *callerso" "const char *calleeso" "const char *calleefun" "void *stack"
 .Sh DESCRIPTION
 .Nm
 is a self-contained shared object providing run-time
@@ -169,13 +172,6 @@ might be called for functions called on its behalf,
 or that multiple threads could enter
 .Fn _rtld_functrace
 at the same time.
-.Pp
-The signature for
-.Fn _rtld_functrace
-is specified as follows.
-.Pp
-.Ft int
-.Fn _rtld_functrace "const char *callerso" "const char *calleeso" "const char *calleefun" "void *stack"
 .Sh DIFFERENCES BETWEEN .1 and .2
 ABI changes have been made to support TLS allocation and initialization
 and to give threading libraries a chance to complete initialization of the
@@ -185,6 +181,38 @@ libraries.
 .Bl -tag -width indent
 .It Pa /var/run/ld-elf.so.hints
 .El
+.Sh EXAMPLES
+To set up an
+.Fn _rtld_functrace
+for printing out the functions as they are called, this code can be used:
+.Bd -literal -offset indent
+#include <string.h>
+
+int nl = 10;
+
+int
+_rtld_functrace(const char *callerso, const char *calleeso,
+    const char *calleefun, void *stack)
+{
+	write(2, "calling ", 8);
+	write(2, calleefun, strlen(calleefun));
+	write(2, &nl, 1);
+	return 1;
+}
+.Ed
+.Pp
+If put in a file named
+.Pa ft.c
+and compiled with
+.Bd -literal -offset indent
+$ cc -shared ft.c -o ft.so
+.Ed
+.Pp
+setting
+.Ev LD_PRELOAD
+to the path of
+.Pa ft.so
+will activate it.
 .Sh SEE ALSO
 .Xr ld 1 ,
 .Xr ldd 1 ,
-- 
2.41.0