Provide an example to the kqueue man page, showing

a basic usage example.  Although it is an
untypical example for the use of kqueue, it is
better than nothing and should get people started.

PR:			196844
Submitted by:		fernando.apesteguia@gmail.com
Reviewed by:		kib
Approved by:		kib
MFC after:		5 days
Differential Revision:	https://reviews.freebsd.org/D6082

1 files changed, 52 insertions, 1 deletions

diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2
index ca94852..2fda40f 100644
--- a/lib/libc/sys/kqueue.2
+++ b/lib/libc/sys/kqueue.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 4, 2015
+.Dd May 1, 2016
 .Dt KQUEUE 2
 .Os
 .Sh NAME
@@ -603,6 +603,57 @@ will be set to indicate the error condition.
 If the time limit expires, then
 .Fn kevent
 returns 0.
+.Sh EXAMPLES
+.Bd -literal -compact
+#include <sys/types.h>
+#include <sys/event.h>
+#include <sys/time.h>
+#include <err.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+int
+main(int argc, char **argv)
+{
+    struct kevent event;    /* Event we want to monitor */
+    struct kevent tevent;   /* Event triggered */
+    int kq, fd, ret;
+
+    if (argc != 2)
+	err(EXIT_FAILURE, "Usage: %s path\en", argv[0]);
+    fd = open(argv[1], O_RDONLY);
+    if (fd == -1)
+	err(EXIT_FAILURE, "Failed to open '%s'", argv[1]);
+
+    /* Create kqueue. */
+    kq = kqueue();
+    if (kq == -1)
+	err(EXIT_FAILURE, "kqueue() failed");
+
+    /* Initialize kevent structure. */
+    EV_SET(&event, fd, EVFILT_VNODE, EV_ADD | EV_CLEAR, NOTE_WRITE,
+	0, NULL);
+    /* Attach event to the kqueue. */
+    ret = kevent(kq, &event, 1, NULL, 0, NULL);
+    if (ret == -1)
+	err(EXIT_FAILURE, "kevent register");
+    if (event.flags & EV_ERROR)
+	errx(EXIT_FAILURE, "Event error: %s", strerror(event.data));
+
+    for (;;) {
+	/* Sleep until something happens. */
+	ret = kevent(kq, NULL, 0, &tevent, 1, NULL);
+	if (ret == -1) {
+	    err(EXIT_FAILURE, "kevent wait");
+	} else if (ret > 0) {
+	    printf("Something was written in '%s'\en", argv[1]);
+	}
+    }
+}
+.Ed
 .Sh ERRORS
 The
 .Fn kqueue