usr.sbin/autofs: Cleanup workaround code for a VFS bug
[dragonfly.git] / lib / libcam / cam.3
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 .\"
30 .Dd October 10, 1998
31 .Dt CAM 3
32 .Os
33 .Sh NAME
34 .Nm cam_open_device ,
35 .Nm cam_open_spec_device ,
36 .Nm cam_open_btl ,
37 .Nm cam_open_pass ,
38 .Nm cam_close_device ,
39 .Nm cam_close_spec_device ,
40 .Nm cam_getccb ,
41 .Nm cam_send_ccb ,
42 .Nm cam_freeccb ,
43 .Nm cam_path_string ,
44 .Nm cam_device_dup ,
45 .Nm cam_device_copy ,
46 .Nm cam_get_device
47 .Nd CAM user library
48 .Sh LIBRARY
49 .Lb libcam
50 .Sh SYNOPSIS
51 .In stdio.h
52 .In camlib.h
53 .Ft struct cam_device *
54 .Fo cam_open_device
55 .Fa "const char *path"
56 .Fa "int flags"
57 .Fc
58 .Ft struct cam_device *
59 .Fo cam_open_spec_device
60 .Fa "const char *dev_name"
61 .Fa "int unit"
62 .Fa "int flags"
63 .Fa "struct cam_device *device"
64 .Fc
65 .Ft struct cam_device *
66 .Fo cam_open_btl
67 .Fa "path_id_t path_id"
68 .Fa "target_id_t target_id"
69 .Fa "lun_id_t target_lun"
70 .Fa "int flags"
71 .Fa "struct cam_device *device"
72 .Fc
73 .Ft struct cam_device *
74 .Fo cam_open_pass
75 .Fa "const char *path"
76 .Fa "int flags"
77 .Fa "struct cam_device *device"
78 .Fc
79 .Ft void
80 .Fo cam_close_device
81 .Fa "struct cam_device *dev"
82 .Fc
83 .Ft void
84 .Fo cam_close_spec_device
85 .Fa "struct cam_device *dev"
86 .Fc
87 .Ft union ccb *
88 .Fo cam_getccb
89 .Fa "struct cam_device *dev"
90 .Fc
91 .Ft int
92 .Fo cam_send_ccb
93 .Fa "struct cam_device *device"
94 .Fa "union ccb *ccb"
95 .Fc
96 .Ft void
97 .Fo cam_freeccb
98 .Fa "union ccb *ccb"
99 .Fc
100 .Ft char *
101 .Fo cam_path_string
102 .Fa "struct cam_device *dev"
103 .Fa "char *str"
104 .Fa "int len"
105 .Fc
106 .Ft struct cam_device *
107 .Fo cam_device_dup
108 .Fa "struct cam_device *device"
109 .Fc
110 .Ft void
111 .Fo cam_device_copy
112 .Fa "struct cam_device *src"
113 .Fa "struct cam_device *dst"
114 .Fc
115 .Ft int
116 .Fo cam_get_device
117 .Fa "const char *path"
118 .Fa "char *dev_name"
119 .Fa "int devnamelen"
120 .Fa "int *unit"
121 .Fc
122 .Sh DESCRIPTION
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.
127 .Pp
128 Many of the CAM library functions use the
129 .Va cam_device
130 structure:
131 .Bd -literal
132 struct cam_device {
133         char            device_path[MAXPATHLEN+1];/*
134                                                    * Pathname of the
135                                                    * device given by the
136                                                    * user. This may be
137                                                    * null if the user
138                                                    * states the device
139                                                    * name and unit number
140                                                    * separately.
141                                                    */
142         char            given_dev_name[DEV_IDLEN+1];/*
143                                                      * Device name given by
144                                                      * the user.
145                                                      */
146         u_int32_t       given_unit_number;          /*
147                                                      * Unit number given by
148                                                      * the user.
149                                                      */
150         char            device_name[DEV_IDLEN+1];/*
151                                                   * Name of the device,
152                                                   * e.g. 'pass'
153                                                   */
154         u_int32_t       dev_unit_num;   /* Unit number of the passthrough
155                                          * device associated with this
156                                          * particular device.
157                                          */
158
159         char            sim_name[SIM_IDLEN+1];/*
160                                                * Controller name, e.g.'ahci'
161                                                */
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 */
175 };
176 .Ed
177 .Pp
178 .Fn cam_open_device
179 takes as arguments a string describing the device it is to open, and
180 .Ar flags
181 suitable for passing to
182 .Xr open 2 .
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
186 .Fn cam_get_device
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.
191 .Fn cam_open_device
192 is rather simple to use, but it isn't really suitable for general use
193 because its behavior isn't necessarily deterministic.
194 Programmers writing
195 new applications should make the extra effort to use one of the other open
196 routines documented below.
197 .Pp
198 .Fn cam_open_spec_device
199 opens the
200 .Xr pass 4
201 device that corresponds to the device name and unit number passed in.
202 The
203 .Ar flags
204 should be flags suitable for passing to
205 .Xr open 2 .
206 The
207 .Ar device
208 argument is optional.
209 The user may supply pre-allocated space for the
210 .Va cam_device
211 structure.
212 If the
213 .Ar device
214 argument is
215 .Va NULL ,
216 .Fn cam_open_spec_device
217 will allocate space for the
218 .Va cam_device
219 structure using
220 .Xr malloc 3 .
221 .Pp
222 .Fn cam_open_btl
223 is similar to
224 .Fn cam_open_spec_device ,
225 except that it takes a
226 .Tn SCSI
227 bus, target and logical unit instead of a device name and unit number as
228 arguments.
229 The
230 .Va path_id
231 argument is the CAM equivalent of a
232 .Tn SCSI
233 bus number.
234 It represents the logical bus number in the system.
235 The
236 .Ar flags
237 should be flags suitable for passing to
238 .Xr open 2 .
239 As with
240 .Fn cam_open_spec_device ,
241 the
242 .Fa device
243 argument is optional.
244 .Pp
245 .Fn cam_open_pass
246 takes as an argument the
247 .Fa path
248 of a
249 .Xr pass 4
250 device to open.
251 No translation or lookup is performed, so the path passed
252 in must be that of a CAM
253 .Xr pass 4
254 device.
255 The
256 .Fa flags
257 should be flags suitable for passing to
258 .Xr open 2 .
259 The
260 .Fa device
261 argument, as with
262 .Fn cam_open_spec_device
263 and
264 .Fn cam_open_btl ,
265 should be NULL if the user wants the CAM library to allocate space for the
266 .Va cam_device
267 structure.
268 .Fn cam_close_device
269 frees the
270 .Va cam_device
271 structure allocated by one of the above
272 .Fn open
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
276 .Va cam_device
277 structure.
278 Instead, the user should call
279 .Fn cam_close_spec_device .
280 .Pp
281 .Fn cam_close_spec_device
282 merely closes the file descriptor opened in one of the
283 .Fn open
284 routines described above.
285 This function should be called when the
286 .Va cam_device
287 structure was allocated by the caller, rather than the CAM library.
288 .Pp
289 .Fn cam_getccb
290 allocates a CCB
291 using
292 .Xr malloc 3
293 and sets fields in the CCB header using values from the
294 .Va cam_device
295 structure.
296 .Pp
297 .Fn cam_send_ccb
298 sends the given
299 .Va ccb
300 to the
301 .Fa device
302 described in the
303 .Va cam_device
304 structure.
305 .Pp
306 .Fn cam_freeccb
307 frees CCBs allocated by
308 .Fn cam_getccb .
309 .Pp
310 .Fn cam_path_string
311 takes as arguments a
312 .Va cam_device
313 structure, and a string with length
314 .Fa len .
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): .
318 .Fn cam_path_string
319 will place at most
320 .Fa len Ns \-1
321 characters into
322 .Ar str .
323 The
324 .Ar len Ns 'th
325 character will be the terminating
326 .Ql \e0 .
327 .Pp
328 .Fn cam_device_dup
329 operates in a fashion similar to
330 .Xr strdup 3 .
331 It allocates space for a
332 .Va cam_device
333 structure and copies the contents of the passed-in
334 .Fa device
335 structure to the newly allocated structure.
336 .Pp
337 .Fn cam_device_copy
338 copies the
339 .Fa src
340 structure to
341 .Fa dst .
342 .Pp
343 .Fn cam_get_device
344 takes a
345 .Fa path
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
348 passes them back in
349 .Fa dev_name
350 and
351 .Fa unit ,
352 respectively.
353 .Fn cam_get_device
354 can handle strings of the following forms, at least:
355 .Pp
356 .Bl -tag -width 1234 -compact
357 .It /dev/foo0a
358 .It /dev/foo1s2c
359 .It foo0
360 .It foo0a
361 .It nfoo0
362 .El
363 .Pp
364 .Fn cam_get_device
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.
370 .Sh RETURN VALUES
371 .Fn cam_open_device ,
372 .Fn cam_open_spec_device ,
373 .Fn cam_open_btl ,
374 and
375 .Fn cam_open_pass
376 return a pointer to a
377 .Va cam_device
378 structure, or NULL if there was an error.
379 .Pp
380 .Fn cam_getccb
381 returns an allocated and partially initialized CCB, or NULL if allocation
382 of the CCB failed.
383 .Pp
384 .Fn cam_send_ccb
385 returns a value of -1 if an error occurred, and
386 .Va errno
387 is set to indicate the error.
388 .Pp
389 .Fn cam_path_string
390 returns a filled printing prefix string as a convenience.
391 This is the same
392 .Fa str
393 that is passed into
394 .Fn cam_path_string .
395 .Pp
396 .Fn cam_device_dup
397 returns a copy of the
398 .Va device
399 passed in, or NULL if an error occurred.
400 .Pp
401 .Fn cam_get_device
402 returns 0 for success, and -1 to indicate failure.
403 .Pp
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
406 string
407 .Va cam_errbuf
408 which is
409 .Dv CAM_ERRBUF_SIZE
410 characters long.
411 .Sh SEE ALSO
412 .Xr cam_cdbparse 3 ,
413 .Xr pass 4 ,
414 .Xr camcontrol 8
415 .Sh HISTORY
416 The CAM library first appeared in
417 .Fx 3.0 .
418 .Sh AUTHORS
419 .An Kenneth Merry Aq Mt ken@FreeBSD.org
420 .Sh BUGS
421 .Fn cam_open_device
422 doesn't check to see if the
423 .Fa path
424 passed in is a symlink to something.
425 It also doesn't check to see if the
426 .Fa path
427 passed in is an actual
428 .Xr pass 4
429 device.
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
432 .Xr pass 4
433 device.
434 .Pp
435 Some of the functions are possibly mis-named or poorly named.