cam.3: do not discourage use of cam_open_device

[Kenneth D. Merry]

On Tue, Apr 20, 2010 at 21:01:26 +0300, Andriy Gapon wrote:
> 
> This is based on my understanding what Scott Long tried to explain me a while ago.
> 
> Index: lib/libcam/cam.3
> ===================================================================
> --- lib/libcam/cam.3	(revision 206902)
> +++ lib/libcam/cam.3	(working copy)
> @@ -190,12 +190,6 @@
>  Once the device name and unit number
>  are determined, a lookup is performed to determine the passthrough device
>  that corresponds to the given device.
> -.Fn cam_open_device
> -is rather simple to use, but it is not really suitable for general use
> -because its behavior is not necessarily deterministic.
> -Programmers writing
> -new applications should make the extra effort to use one of the other open
> -routines documented below.
>  .Pp
>  .Fn cam_open_spec_device
>  opens the
> 
> 
> It seems that this warning about ambiguity came from pre-devfs days when e.g. cd0
> nodes in different directories could correspond to different actual SCSI
> peripherals.  It seems that there wasn't an ambiguity if an absolute device path
> was given.
> 
> Nowadays, cam_open_device seems to always do a proper job of finding a correct
> pass device.

The warning had more to do with the ambiguity trying to make sense of
device names than having different device nodes lying around.

cam_get_device() (which is called by cam_open_device()) tries to do
some things that will break on devices that start with n (unless it's a
non-rewound tape device) or r.  Right now we don't have any CAM peripheral
drivers that start with those letters, so it works.  It also won't do the
right thing on devices with gpt partitions.  Some of that can be fixed,
though.

So it's mostly deterministic, but it may not do exactly what you expect.

It may be good to keep some statement in there pointing people to the other
routines as being preferred because they're a little more deterministic.

Ken
-- 
Kenneth Merry
ken at FreeBSD.ORG