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
28 .\" $FreeBSD: src/lib/libcam/cam.3,v 1.5.2.6 2001/12/17 10:08:28 ru Exp $
35 .Nm cam_open_spec_device ,
38 .Nm cam_close_device ,
39 .Nm cam_close_spec_device ,
53 .Ft struct cam_device *
55 .Fa "const char *path"
58 .Ft struct cam_device *
59 .Fo cam_open_spec_device
60 .Fa "const char *dev_name"
63 .Fa "struct cam_device *device"
65 .Ft struct cam_device *
67 .Fa "path_id_t path_id"
68 .Fa "target_id_t target_id"
69 .Fa "lun_id_t target_lun"
71 .Fa "struct cam_device *device"
73 .Ft struct cam_device *
75 .Fa "const char *path"
77 .Fa "struct cam_device *device"
81 .Fa "struct cam_device *dev"
84 .Fo cam_close_spec_device
85 .Fa "struct cam_device *dev"
89 .Fa "struct cam_device *dev"
93 .Fa "struct cam_device *device"
102 .Fa "struct cam_device *dev"
106 .Ft struct cam_device *
108 .Fa "struct cam_device *device"
112 .Fa "struct cam_device *src"
113 .Fa "struct cam_device *dst"
117 .Fa "const char *path"
123 The CAM library consists of a number of functions designed to aid in
124 programming with the CAM subsystem.
125 This man page covers the basic set of library functions.
126 More functions are documented in the man pages listed below.
128 Many of the CAM library functions use the
133 char device_path[MAXPATHLEN+1];/*
135 * device given by the
139 * name and unit number
142 char given_dev_name[DEV_IDLEN+1];/*
143 * Device name given by
146 u_int32_t given_unit_number; /*
147 * Unit number given by
150 char device_name[DEV_IDLEN+1];/*
151 * Name of the device,
154 u_int32_t dev_unit_num; /* Unit number of the passthrough
155 * device associated with this
159 char sim_name[SIM_IDLEN+1];/*
160 * Controller name, e.g.'ahci'
162 u_int32_t sim_unit_number; /* Controller unit number */
163 u_int32_t bus_id; /* Controller bus number */
164 lun_id_t target_lun; /* Logical Unit Number */
165 target_id_t target_id; /* Target ID */
166 path_id_t path_id; /* System SCSI bus number */
167 u_int16_t pd_type; /* type of peripheral device */
168 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */
169 u_int8_t serial_num[252]; /* device serial number */
170 u_int8_t serial_num_len; /* length of the serial number */
171 u_int8_t sync_period; /* Negotiated sync period */
172 u_int8_t sync_offset; /* Negotiated sync offset */
173 u_int8_t bus_width; /* Negotiated bus width */
174 int fd; /* file descriptor for device */
179 takes as arguments a string describing the device it is to open, and
181 suitable for passing to
183 The "path" passed in may actually be most any type of string that contains
184 a device name and unit number to be opened.
185 The string will be parsed by
187 into a device name and unit number.
188 Once the device name and unit number
189 are determined, a lookup is performed to determine the passthrough device
190 that corresponds to the given device.
192 is rather simple to use, but it isn't really suitable for general use
193 because its behavior isn't necessarily deterministic.
195 new applications should make the extra effort to use one of the other open
196 routines documented below.
198 .Fn cam_open_spec_device
201 device that corresponds to the device name and unit number passed in.
204 should be flags suitable for passing to
208 argument is optional.
209 The user may supply pre-allocated space for the
216 .Fn cam_open_spec_device
217 will allocate space for the
224 .Fn cam_open_spec_device ,
225 except that it takes a
227 bus, target and logical unit instead of a device name and unit number as
231 argument is the CAM equivalent of a
234 It represents the logical bus number in the system.
237 should be flags suitable for passing to
240 .Fn cam_open_spec_device ,
243 argument is optional.
246 takes as an argument the
251 No translation or lookup is performed, so the path passed
252 in must be that of a CAM
257 should be flags suitable for passing to
262 .Fn cam_open_spec_device
265 should be NULL if the user wants the CAM library to allocate space for the
271 structure allocated by one of the above
273 calls, and closes the file
274 descriptor to the passthrough device.
275 This routine should not be called if the user allocated space for the
278 Instead, the user should call
279 .Fn cam_close_spec_device .
281 .Fn cam_close_spec_device
282 merely closes the file descriptor opened in one of the
284 routines described above.
285 This function should be called when the
287 structure was allocated by the caller, rather than the CAM library.
293 and sets fields in the CCB header using values from the
307 frees CCBs allocated by
313 structure, and a string with length
315 It creates a colon-terminated printing prefix string similar to the ones
316 used by the kernel, e.g.\&
317 .Dq (cd0:ahc1:0:4:0): .
325 character will be the terminating
329 operates in a fashion similar to
331 It allocates space for a
333 structure and copies the contents of the passed-in
335 structure to the newly allocated structure.
346 argument containing a string with a device name followed by a unit number.
347 It then breaks the string down into a device name and unit number, and
354 can handle strings of the following forms, at least:
356 .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 .
368 Programmers are encouraged to use more deterministic methods of obtaining
369 device names and unit numbers if possible.
371 .Fn cam_open_device ,
372 .Fn cam_open_spec_device ,
376 return a pointer to a
378 structure, or NULL if there was an error.
381 returns an allocated and partially initialized CCB, or NULL if allocation
385 returns a value of -1 if an error occurred, and
387 is set to indicate the error.
390 returns a filled printing prefix string as a convenience.
394 .Fn cam_path_string .
397 returns a copy of the
399 passed in, or NULL if an error occurred.
402 returns 0 for success, and -1 to indicate failure.
404 If an error is returned from one of the base CAM library functions
405 described here, the reason for the error is generally printed in the global
416 The CAM library first appeared in
419 .An Kenneth Merry Aq Mt ken@FreeBSD.org
422 doesn't check to see if the
424 passed in is a symlink to something.
425 It also doesn't check to see if the
427 passed in is an actual
430 The former would be rather easy to implement, but the latter would
431 require a definitive way to identify a device node as a
435 Some of the functions are possibly mis-named or poorly named.