2 .\" Copyright (c) 1998 Kenneth D. Merry.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. The name of the author may not be used to endorse or promote products
14 .\" derived from this software without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nm cam_open_spec_device ,
36 .Nm cam_close_device ,
37 .Nm cam_close_spec_device ,
51 .Ft struct cam_device *
53 .Fa "const char *path"
56 .Ft struct cam_device *
57 .Fo cam_open_spec_device
58 .Fa "const char *dev_name"
61 .Fa "struct cam_device *device"
63 .Ft struct cam_device *
65 .Fa "path_id_t path_id"
66 .Fa "target_id_t target_id"
67 .Fa "lun_id_t target_lun"
69 .Fa "struct cam_device *device"
71 .Ft struct cam_device *
73 .Fa "const char *path"
75 .Fa "struct cam_device *device"
79 .Fa "struct cam_device *dev"
82 .Fo cam_close_spec_device
83 .Fa "struct cam_device *dev"
87 .Fa "struct cam_device *dev"
91 .Fa "struct cam_device *device"
100 .Fa "struct cam_device *dev"
104 .Ft struct cam_device *
106 .Fa "struct cam_device *device"
110 .Fa "struct cam_device *src"
111 .Fa "struct cam_device *dst"
115 .Fa "const char *path"
121 The CAM library consists of a number of functions designed to aid in
122 programming with the CAM subsystem described in
124 This man page covers the basic set of
126 More functions are documented in the man pages listed
129 Many of the CAM library functions use the
134 char device_path[MAXPATHLEN+1];/*
136 * device given by the
140 * name and unit number
143 char given_dev_name[DEV_IDLEN+1];/*
144 * Device name given by
147 uint32_t given_unit_number; /*
148 * Unit number given by
151 char device_name[DEV_IDLEN+1];/*
152 * Name of the device,
155 uint32_t dev_unit_num; /* Unit number of the passthrough
156 * device associated with this
160 char sim_name[SIM_IDLEN+1];/*
161 * Controller name, e.g., 'ahc'
163 uint32_t sim_unit_number; /* Controller unit number */
164 uint32_t bus_id; /* Controller bus number */
165 lun_id_t target_lun; /* Logical Unit Number */
166 target_id_t target_id; /* Target ID */
167 path_id_t path_id; /* System SCSI bus number */
168 uint16_t pd_type; /* type of peripheral device */
169 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */
170 uint8_t serial_num[252]; /* device serial number */
171 uint8_t serial_num_len; /* length of the serial number */
172 uint8_t sync_period; /* Negotiated sync period */
173 uint8_t sync_offset; /* Negotiated sync offset */
174 uint8_t bus_width; /* Negotiated bus width */
175 int fd; /* file descriptor for device */
180 takes as arguments a string describing the device it is to open, and
182 suitable for passing to
184 The "path" passed in may actually be most any type of string that contains
185 a device name and unit number to be opened.
186 The string will be parsed by
188 into a device name and unit number.
189 Once the device name and unit number
190 are determined, a lookup is performed to determine the passthrough device
191 that corresponds to the given device.
193 .Fn cam_open_spec_device
196 device that corresponds to the device name and unit number passed in.
199 should be flags suitable for passing to
203 argument is optional.
204 The user may supply pre-allocated space for the
211 .Fn cam_open_spec_device
212 will allocate space for the
219 .Fn cam_open_spec_device ,
220 except that it takes a SCSI bus,
221 target and logical unit instead of a device name and unit number as
225 argument is the CAM equivalent of a SCSI bus number.
226 It represents the logical bus number in the system.
229 should be flags suitable for passing to
232 .Fn cam_open_spec_device ,
235 argument is optional.
238 takes as an argument the
243 No translation or lookup is performed, so the path passed
244 in must be that of a CAM
249 should be flags suitable for passing to
254 .Fn cam_open_spec_device
259 if the user wants the CAM library to allocate space for the
266 structure allocated by one of the above
268 calls, and closes the file
269 descriptor to the passthrough device.
270 This routine should not be called if
271 the user allocated space for the
274 Instead, the user should call
275 .Fn cam_close_spec_device .
277 .Fn cam_close_spec_device
278 merely closes the file descriptor opened in one of the
282 This function should be called when the
284 structure was allocated by the caller, rather than the CAM library.
287 allocates a prezeroed CCB
290 and sets fields in the CCB header using values from the
304 frees CCBs allocated by
315 structure, and a string with length
317 It creates a colon-terminated printing prefix string similar to the ones
319 e.g.: "(cd0:ahc1:0:4:0): ".
327 character will be the terminating
331 operates in a fashion similar to
333 It allocates space for a
335 structure and copies the contents of the passed-in
337 structure to the newly allocated structure.
348 argument containing a string with a device name followed by a unit number.
349 It then breaks the string down into a device name and unit number, and
356 can handle strings of the following forms, at least:
358 .Bl -tag -width 1234 -compact
365 is provided as a convenience function for applications that need to provide
366 functionality similar to
367 .Fn cam_open_device .
369 .Fn cam_open_device ,
370 .Fn cam_open_spec_device ,
374 return a pointer to a
378 if there was an error.
381 returns an allocated and partially initialized CCB, or
383 if allocation of the CCB failed.
386 returns a value of -1 if an error occurred, and
388 is set to indicate the error.
391 returns a filled printing prefix string as a convenience.
395 .Fn cam_path_string .
398 returns a copy of the
402 if an error occurred.
405 returns 0 for success, and -1 to indicate failure.
407 If an error is returned from one of the base CAM library functions
408 described here, the reason for the error is generally printed in the global
419 The CAM library first appeared in
422 .An Kenneth Merry Aq Mt ken@FreeBSD.org
425 does not check to see if the
427 passed in is a symlink to something.
428 It also does not check to see if the
430 passed in is an actual
433 The former would be rather easy to implement, but the latter would
434 require a definitive way to identify a device node as a
438 Some of the functions are possibly misnamed or poorly named.