svn commit: r299190 - stable/10/lib/libc/sys

[Benedict Reuschling]

Author: bcr (doc committer)
Date: Fri May  6 17:55:11 2016
New Revision: 299190
URL: https://svnweb.freebsd.org/changeset/base/299190

Log:
  MFC r298893:
  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 at gmail.com
  Reviewed by:	kib
  Approved by:	kib
  Differential Revision:  https://reviews.freebsd.org/D6082

Modified:
  stable/10/lib/libc/sys/kqueue.2
Directory Properties:
  stable/10/   (props changed)

Modified: stable/10/lib/libc/sys/kqueue.2
==============================================================================
--- stable/10/lib/libc/sys/kqueue.2	Fri May  6 17:39:12 2016	(r299189)
+++ stable/10/lib/libc/sys/kqueue.2	Fri May  6 17:55:11 2016	(r299190)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 29, 2015
+.Dd May 1, 2016
 .Dt KQUEUE 2
 .Os
 .Sh NAME
@@ -577,6 +577,57 @@ will be set to indicate the error condit
 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