docs/176197: [PATCH] Add example to qsort.3

[Fernando]

>Number:         176197
>Category:       docs
>Synopsis:       [PATCH] Add example to qsort.3
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat Feb 16 18:00:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Fernando
>Release:        9.0-RELEASE
>Organization:
Open Sistemas
>Environment:
FreeBSD hammer 9.0-RELEASE FreeBSD 9.0-RELEASE #0: Tue Jan  3 07:46:30 UTC 2012     root at farrell.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC  amd64

>Description:
qsort(3) lacks an example in the man page. If we want to have the best documentation available, we need examples in some man pages.
>How-To-Repeat:
man qsort

It doesn't show an example of use
>Fix:
Apply the attached patch.

Patch attached with submission follows:

--- lib/libc/stdlib/qsort.3	2012-01-03 04:26:05.000000000 +0100
+++ /home/fernape/Programming/FreeBSD/qsort_man/qsort.3	2013-02-16 18:42:44.000000000 +0100
@@ -211,6 +211,52 @@
 did not permit the comparison routine itself to call
 .Fn qsort 3 .
 This is no longer true.
+.Sh EXAMPLES
+Sort an array of integers.
+.Bd -literal
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/*
+ * Custom comparison function
+ */
+static int
+str_compare(const void *p1, const void *p2)
+{
+
+	/* Cast and dereference */
+	if (*(int *)p1 < *(int *)p2)
+		return (-1);
+
+	if (*(int *)p1 > *(int *)p2)
+		return (1);
+
+	return (0);
+
+}
+
+/*
+ * Sort an array of integers
+ */
+int
+main(int argc, char **argv)
+{
+	int i;
+	int int_array[] = {4, 5, 9, 3, 1, 7, 2, 8, 6};
+	const int array_size = sizeof(int_array) / sizeof(int);
+
+	/* Sort array */
+	qsort(&int_array, array_size, sizeof(int), str_compare);
+
+	/* Print out sorted array */
+	for (i = 0; i < array_size; i++) {
+		printf("%d\n", int_array[i]);
+	}
+
+	exit(EXIT_SUCCESS);
+}
+.Ed
 .Sh ERRORS
 The
 .Fn heapsort


>Release-Note:
>Audit-Trail:
>Unformatted: