Clarify zpool_events_next() comment

Due to the very poorly chosen argument name 'cleanup_fd' it was
completely unclear that this file descriptor is used to track the
current cursor location.  When the file descriptor is created by
opening ZFS_DEV a private cursor is created in the kernel for the
returned file descriptor.  Subsequent calls to zpool_events_next()
and zpool_events_seek() then require the file descriptor as an
argument to reposition the cursor.  When the file descriptor is
closed the kernel state tracking the cursor is destroyed.

This patch contains no functional change, it just changes a
few variable names and clarifies the documentation.

Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Chris Dunlap <cdunlap@llnl.gov>
Issue #2

cmd/zpool/zpool_main.c

@@ -5455,17 +5455,17 @@ static int
 zpool_do_events_next(ev_opts_t *opts)
 {
 	nvlist_t *nvl;
-	int cleanup_fd, ret, dropped;
+	int zevent_fd, ret, dropped;
 
-	cleanup_fd = open(ZFS_DEV, O_RDWR);
+	zevent_fd = open(ZFS_DEV, O_RDWR);
-	VERIFY(cleanup_fd >= 0);
+	VERIFY(zevent_fd >= 0);
 
 	if (!opts->scripted)
 		(void) printf(gettext("%-30s %s\n"), "TIME", "CLASS");
 
 	while (1) {
 		ret = zpool_events_next(g_zfs, &nvl, &dropped,
-		    !!opts->follow, cleanup_fd);
+		    !!opts->follow, zevent_fd);
 		if (ret || nvl == NULL)
 			break;
 
@@ -5483,7 +5483,7 @@ zpool_do_events_next(ev_opts_t *opts)
 		nvlist_free(nvl);
 	}
 
-	VERIFY(0 == close(cleanup_fd));
+	VERIFY(0 == close(zevent_fd));
 
 	return (ret);
 }

lib/libzfs/libzfs_pool.c

@@ -3783,25 +3783,25 @@ zpool_get_history(zpool_handle_t *zhp, nvlist_t **nvhisp)
 }
 
 /*
- * Retrieve the next event.  If there is a new event available 'nvp' will
+ * Retrieve the next event given the passed 'zevent_fd' file descriptor.
- * contain a newly allocated nvlist and 'dropped' will be set to the number
+ * If there is a new event available 'nvp' will contain a newly allocated
- * of missed events since the last call to this function.  When 'nvp' is
+ * nvlist and 'dropped' will be set to the number of missed events since
- * set to NULL it indicates no new events are available.  In either case
+ * the last call to this function.  When 'nvp' is set to NULL it indicates
- * the function returns 0 and it is up to the caller to free 'nvp'.  In
+ * no new events are available.  In either case the function returns 0 and
- * the case of a fatal error the function will return a non-zero value.
+ * it is up to the caller to free 'nvp'.  In the case of a fatal error the
- * When the function is called in blocking mode it will not return until
+ * function will return a non-zero value.  When the function is called in
- * a new event is available.
+ * blocking mode it will not return until a new event is available.
  */
 int
 zpool_events_next(libzfs_handle_t *hdl, nvlist_t **nvp,
-    int *dropped, int block, int cleanup_fd)
+    int *dropped, int block, int zevent_fd)
 {
 	zfs_cmd_t zc = {"\0"};
 	int error = 0;
 
 	*nvp = NULL;
 	*dropped = 0;
-	zc.zc_cleanup_fd = cleanup_fd;
+	zc.zc_cleanup_fd = zevent_fd;
 
 	if (!block)
 		zc.zc_guid = ZEVENT_NONBLOCK;

module/zfs/zfs_ioctl.c

@@ -4860,11 +4860,11 @@ zfs_ioc_release(const char *pool, nvlist_t *holds, nvlist_t *errlist)
 /*
  * inputs:
  * zc_guid		flags (ZEVENT_NONBLOCK)
+ * zc_cleanup_fd	zevent file descriptor
  *
  * outputs:
  * zc_nvlist_dst	next nvlist event
  * zc_cookie		dropped events since last get
- * zc_cleanup_fd	cleanup-on-exit file descriptor
  */
 static int
 zfs_ioc_events_next(zfs_cmd_t *zc)