| blob | 7d4ea0e5a4c4bc6c00d4b5dffe86d2cec4da4acc |
1 .\"
2 .\" Copyright (c) 1998 Kenneth D. Merry.
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
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.
15 .\"
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
26 .\" SUCH DAMAGE.
27 .\"
28 .\" $FreeBSD: src/lib/libcam/cam.3,v 1.5.2.6 2001/12/17 10:08:28 ru Exp $
29 .\" $DragonFly: src/lib/libcam/cam.3,v 1.3 2007/05/13 18:33:56 swildner Exp $
30 .\"
31 .Dd October 10, 1998
32 .Os
33 .Dt CAM 3
34 .Sh NAME
35 .Nm cam_open_device ,
36 .Nm cam_open_spec_device ,
37 .Nm cam_open_btl ,
38 .Nm cam_open_pass ,
39 .Nm cam_close_device ,
40 .Nm cam_close_spec_device ,
41 .Nm cam_getccb ,
42 .Nm cam_send_ccb ,
43 .Nm cam_freeccb ,
44 .Nm cam_path_string ,
45 .Nm cam_device_dup ,
46 .Nm cam_device_copy ,
47 .Nm cam_get_device
48 .Nd CAM user library
49 .Sh LIBRARY
50 .Lb libcam
51 .Sh SYNOPSIS
52 .In stdio.h
53 .In camlib.h
54 .Ft struct cam_device *
55 .Fo cam_open_device
56 .Fa "const char *path"
57 .Fa "int flags"
58 .Fc
59 .Ft struct cam_device *
60 .Fo cam_open_spec_device
61 .Fa "const char *dev_name"
62 .Fa "int unit"
63 .Fa "int flags"
64 .Fa "struct cam_device *device"
65 .Fc
66 .Ft struct cam_device *
67 .Fo cam_open_btl
68 .Fa "path_id_t path_id"
69 .Fa "target_id_t target_id"
70 .Fa "lun_id_t target_lun"
71 .Fa "int flags"
72 .Fa "struct cam_device *device"
73 .Fc
74 .Ft struct cam_device *
75 .Fo cam_open_pass
76 .Fa "const char *path"
77 .Fa "int flags"
78 .Fa "struct cam_device *device"
79 .Fc
80 .Ft void
81 .Fo cam_close_device
82 .Fa "struct cam_device *dev"
83 .Fc
84 .Ft void
85 .Fo cam_close_spec_device
86 .Fa "struct cam_device *dev"
87 .Fc
88 .Ft union ccb *
89 .Fo cam_getccb
90 .Fa "struct cam_device *dev"
91 .Fc
92 .Ft int
93 .Fo cam_send_ccb
94 .Fa "struct cam_device *device"
95 .Fa "union ccb *ccb"
96 .Fc
97 .Ft void
98 .Fo cam_freeccb
99 .Fa "union ccb *ccb"
100 .Fc
101 .Ft char *
102 .Fo cam_path_string
103 .Fa "struct cam_device *dev"
104 .Fa "char *str"
105 .Fa "int len"
106 .Fc
107 .Ft struct cam_device *
108 .Fo cam_device_dup
109 .Fa "struct cam_device *device"
110 .Fc
111 .Ft void
112 .Fo cam_device_copy
113 .Fa "struct cam_device *src"
114 .Fa "struct cam_device *dst"
115 .Fc
116 .Ft int
117 .Fo cam_get_device
118 .Fa "const char *path"
119 .Fa "char *dev_name"
120 .Fa "int devnamelen"
121 .Fa "int *unit"
122 .Fc
123 .Sh DESCRIPTION
124 The CAM library consists of a number of functions designed to aid in
125 programming with the CAM subsystem. This man page covers the basic set of
126 library functions. More functions are documented in the man pages listed
127 below.
128 .Pp
129 Many of the CAM library functions use the
130 .Va cam_device
131 structure:
132 .Bd -literal
133 struct cam_device {
134 char device_path[MAXPATHLEN+1];/*
135 * Pathname of the
136 * device given by the
137 * user. This may be
138 * null if the user
139 * states the device
140 * name and unit number
141 * separately.
142 */
143 char given_dev_name[DEV_IDLEN+1];/*
144 * Device name given by
145 * the user.
146 */
147 u_int32_t given_unit_number; /*
148 * Unit number given by
149 * the user.
150 */
151 char device_name[DEV_IDLEN+1];/*
152 * Name of the device,
153 * e.g. 'pass'
154 */
155 u_int32_t dev_unit_num; /* Unit number of the passthrough
156 * device associated with this
157 * particular device.
158 */
160 char sim_name[SIM_IDLEN+1];/*
161 * Controller name, e.g.'ahc'
162 */
163 u_int32_t sim_unit_number; /* Controller unit number */
164 u_int32_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 u_int16_t pd_type; /* type of peripheral device */
169 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */
170 u_int8_t serial_num[252]; /* device serial number */
171 u_int8_t serial_num_len; /* length of the serial number */
172 u_int8_t sync_period; /* Negotiated sync period */
173 u_int8_t sync_offset; /* Negotiated sync offset */
174 u_int8_t bus_width; /* Negotiated bus width */
175 int fd; /* file descriptor for device */
176 };
177 .Ed
178 .Pp
179 .Fn cam_open_device
180 takes as arguments a string describing the device it is to open, and
181 .Ar flags
182 suitable for passing to
183 .Xr open 2 .
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. The string will be parsed by
186 .Fn cam_get_device
187 into a device name and unit number. Once the device name and unit number
188 are determined, a lookup is performed to determine the passthrough device
189 that corresponds to the given device.
190 .Fn cam_open_device
191 is rather simple to use, but it isn't really suitable for general use
192 because its behavior isn't necessarily deterministic. Programmers writing
193 new applications should make the extra effort to use one of the other open
194 routines documented below.
195 .Pp
196 .Fn cam_open_spec_device
197 opens the
198 .Xr pass 4
199 device that corresponds to the device name and unit number passed in. The
200 .Ar flags
201 should be flags suitable for passing to
202 .Xr open 2 .
203 The
204 .Ar device
205 argument is optional. The user may supply pre-allocated space for the
206 .Va cam_device
207 structure. If the
208 .Ar device
209 argument is
210 .Va NULL ,
211 .Fn cam_open_spec_device
212 will allocate space for the
213 .Va cam_device
214 structure using
215 .Xr malloc 3 .
216 .Pp
217 .Fn cam_open_btl
218 is similar to
219 .Fn cam_open_spec_device ,
220 except that it takes a
221 .Tn SCSI
222 bus, target and logical unit instead of a device name and unit number as
223 arguments. The
224 .Va path_id
225 argument is the CAM equivalent of a
226 .Tn SCSI
227 bus number. It represents the logical bus number in the system. The
228 .Ar flags
229 should be flags suitable for passing to
230 .Xr open 2 .
231 As with
232 .Fn cam_open_spec_device ,
233 the
234 .Fa device
235 argument is optional.
236 .Pp
237 .Fn cam_open_pass
238 takes as an argument the
239 .Fa path
240 of a
241 .Xr pass 4
242 device to open. No translation or lookup is performed, so the path passed
243 in must be that of a CAM
244 .Xr pass 4
245 device. The
246 .Fa flags
247 should be flags suitable for passing to
248 .Xr open 2 .
249 The
250 .Fa device
251 argument, as with
252 .Fn cam_open_spec_device
253 and
254 .Fn cam_open_btl ,
255 should be NULL if the user wants the CAM library to allocate space for the
256 .Va cam_device
257 structure.
258 .Fn cam_close_device
259 frees the
260 .Va cam_device
261 structure allocated by one of the above open() calls, and closes the file
262 descriptor to the passthrough device. This routine should not be called if
263 the user allocated space for the
264 .Va cam_device
265 structure. Instead, the user should call
266 .Fn cam_close_spec_device .
267 .Pp
268 .Fn cam_close_spec_device
269 merely closes the file descriptor opened in one of the open() routines
270 described above. This function should be called when the
271 .Va cam_device
272 structure was allocated by the caller, rather than the CAM library.
273 .Pp
274 .Fn cam_getccb
275 allocates a CCB
276 using
277 .Xr malloc 3
278 and sets fields in the CCB header using values from the
279 .Va cam_device
280 structure.
281 .Pp
282 .Fn cam_send_ccb
283 sends the given
284 .Va ccb
285 to the
286 .Fa device
287 described in the
288 .Va cam_device
289 structure.
290 .Pp
291 .Fn cam_freeccb
292 frees CCBs allocated by
293 .Fn cam_getccb .
294 .Pp
295 .Fn cam_path_string
296 takes as arguments a
297 .Va cam_device
298 structure, and a string with length
299 .Fa len .
300 It creates a colon-terminated printing prefix string similar to the ones
301 used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ".
302 .Fn cam_path_string
303 will place at most
304 .Fa len Ns \-1
305 characters into
306 .Ar str .
307 The
308 .Ar len Ns 'th
309 character will be the terminating
310 .Ql \e0 .
311 .Pp
312 .Fn cam_device_dup
313 operates in a fashion similar to
314 .Xr strdup 3 .
315 It allocates space for a
316 .Va cam_device
317 structure and copies the contents of the passed-in
318 .Fa device
319 structure to the newly allocated structure.
320 .Pp
321 .Fn cam_device_copy
322 copies the
323 .Fa src
324 structure to
325 .Fa dst .
326 .Pp
327 .Fn cam_get_device
328 takes a
329 .Fa path
330 argument containing a string with a device name followed by a unit number.
331 It then breaks the string down into a device name and unit number, and
332 passes them back in
333 .Fa dev_name
334 and
335 .Fa unit ,
336 respectively.
337 .Fn cam_get_device
338 can handle strings of the following forms, at least:
339 .Pp
340 .Bl -tag -width 1234 -compact
341 .It /dev/foo0a
342 .It /dev/foo1s2c
343 .It foo0
344 .It foo0a
345 .It nfoo0
346 .El
347 .Pp
348 .Fn cam_get_device
349 is provided as a convenience function for applications that need to provide
350 functionality similar to
351 .Fn cam_open_device .
352 Programmers are encouraged to use more deterministic methods of obtaining
353 device names and unit numbers if possible.
354 .Sh RETURN VALUES
355 .Fn cam_open_device ,
356 .Fn cam_open_spec_device ,
357 .Fn cam_open_btl ,
358 and
359 .Fn cam_open_pass
360 return a pointer to a
361 .Va cam_device
362 structure, or NULL if there was an error.
363 .Pp
364 .Fn cam_getccb
365 returns an allocated and partially initialized CCB, or NULL if allocation
366 of the CCB failed.
367 .Pp
368 .Fn cam_send_ccb
369 returns a value of -1 if an error occurred, and
370 .Va errno
371 is set to indicate the error.
372 .Pp
373 .Fn cam_path_string
374 returns a filled printing prefix string as a convenience. This is the same
375 .Fa str
376 that is passed into
377 .Fn cam_path_string .
378 .Pp
379 .Fn cam_device_dup
380 returns a copy of the
381 .Va device
382 passed in, or NULL if an error occurred.
383 .Pp
384 .Fn cam_get_device
385 returns 0 for success, and -1 to indicate failure.
386 .Pp
387 If an error is returned from one of the base CAM library functions
388 described here, the reason for the error is generally printed in the global
389 string
390 .Va cam_errbuf
391 which is
392 .Dv CAM_ERRBUF_SIZE
393 characters long.
394 .Sh SEE ALSO
395 .Xr cam_cdbparse 3 ,
396 .Xr pass 4 ,
397 .Xr camcontrol 8
398 .Sh HISTORY
399 The CAM library first appeared in
400 .Fx 3.0 .
401 .Sh AUTHORS
402 .An Kenneth Merry Aq ken@FreeBSD.org
403 .Sh BUGS
404 .Fn cam_open_device
405 doesn't check to see if the
406 .Fa path
407 passed in is a symlink to something. It also doesn't check to see if the
408 .Fa path
409 passed in is an actual
410 .Xr pass 4
411 device. The former would be rather easy to implement, but the latter would
412 require a definitive way to identify a device node as a
413 .Xr pass 4
414 device.
415 .Pp
416 Some of the functions are possibly mis-named or poorly named.