svn commit: r315606 - stable/10/lib/libcam

[Ngie Cooper]

Author: ngie
Date: Mon Mar 20 03:00:22 2017
New Revision: 315606
URL: https://svnweb.freebsd.org/changeset/base/315606

Log:
  MFC r315132,r315133,r315186:
  
  r315132:
  
  Use .Dv when referencing NULL
  
  This is the correct markup macro, as opposed to .Va (variable names)
  
  While here, annotate several bare references to `NULL` with .Dv.
  
  r315133:
  
  lib/libcam/cam.3: fix manpage warnings
  
  - spelling: "mis-named" should be "misnamed".
  - delete spaces interspersed in literal representation of
    `struct cam_device` as hard-tabs separate the types and fields.
  - Add commas after `e.g.`.
  
  r315186:
  
  lib/libcam/cam.3: note that cam_freeccb(3) with ccb == NULL is a no-op
  
  This allows me to accurately test this scenario, and for others to rely
  on the behavior, instead of relying on knowledge obtained via code
  inspection.
  
  Wording borrowed from free(3).
  
  Requested by:	ken (D9928)

Modified:
  stable/10/lib/libcam/cam.3
Directory Properties:
  stable/10/   (props changed)

Modified: stable/10/lib/libcam/cam.3
==============================================================================
--- stable/10/lib/libcam/cam.3	Mon Mar 20 03:00:19 2017	(r315605)
+++ stable/10/lib/libcam/cam.3	Mon Mar 20 03:00:22 2017	(r315606)
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 10, 1998
+.Dd March 11, 2017
 .Dt CAM 3
 .Os
 .Sh NAME
@@ -132,7 +132,7 @@ Many of the CAM library functions use th
 structure:
 .Bd -literal
 struct cam_device {
-	char 		device_path[MAXPATHLEN+1];/*
+	char		device_path[MAXPATHLEN+1];/*
 						   * Pathname of the
 						   * device given by the
 						   * user. This may be
@@ -151,7 +151,7 @@ struct cam_device {
 						     */
 	char		device_name[DEV_IDLEN+1];/*
 						  * Name of the device,
-						  * e.g. 'pass'
+						  * e.g., 'pass'
 						  */
 	uint32_t	dev_unit_num;	/* Unit number of the passthrough
 					 * device associated with this
@@ -159,7 +159,7 @@ struct cam_device {
 					 */
 
 	char		sim_name[SIM_IDLEN+1];/*
-					       * Controller name, e.g.'ahc'
+					       * Controller name, e.g., 'ahc'
 					       */
 	uint32_t	sim_unit_number; /* Controller unit number */
 	uint32_t	bus_id;		 /* Controller bus number */
@@ -208,7 +208,7 @@ structure.
 If the
 .Ar device
 argument is
-.Va NULL ,
+.Dv NULL ,
 .Fn cam_open_spec_device
 will allocate space for the
 .Va cam_device
@@ -258,7 +258,9 @@ argument, as with
 .Fn cam_open_spec_device
 and
 .Fn cam_open_btl ,
-should be NULL if the user wants the CAM library to allocate space for the
+should be
+.Dv NULL
+if the user wants the CAM library to allocate space for the
 .Va cam_device
 structure.
 .Fn cam_close_device
@@ -300,6 +302,11 @@ structure.
 .Fn cam_freeccb
 frees CCBs allocated by
 .Fn cam_getccb .
+If
+.Va ccb
+is
+.Dv NULL ,
+no action is taken.
 .Pp
 .Fn cam_path_string
 takes as arguments a
@@ -365,11 +372,14 @@ and
 .Fn cam_open_pass
 return a pointer to a
 .Va cam_device
-structure, or NULL if there was an error.
+structure, or
+.Dv NULL
+if there was an error.
 .Pp
 .Fn cam_getccb
-returns an allocated and partially initialized CCB, or NULL if allocation
-of the CCB failed.
+returns an allocated and partially initialized CCB, or
+.Dv NULL
+if allocation of the CCB failed.
 .Pp
 .Fn cam_send_ccb
 returns a value of -1 if an error occurred, and
@@ -386,7 +396,9 @@ that is passed into
 .Fn cam_device_dup
 returns a copy of the
 .Va device
-passed in, or NULL if an error occurred.
+passed in, or
+.Dv NULL
+if an error occurred.
 .Pp
 .Fn cam_get_device
 returns 0 for success, and -1 to indicate failure.
@@ -422,4 +434,4 @@ require a definitive way to identify a d
 .Xr pass 4
 device.
 .Pp
-Some of the functions are possibly mis-named or poorly named.
+Some of the functions are possibly misnamed or poorly named.