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 124The CAM library consists of a number of functions designed to aid in 125programming with the CAM subsystem. This man page covers the basic set of 126library functions. More functions are documented in the man pages listed 127below. 128.Pp 129Many of the CAM library functions use the 130.Va cam_device 131structure: 132.Bd -literal 133struct 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 */ 159 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 180takes as arguments a string describing the device it is to open, and 181.Ar flags 182suitable for passing to 183.Xr open 2 . 184The "path" passed in may actually be most any type of string that contains 185a device name and unit number to be opened. The string will be parsed by 186.Fn cam_get_device 187into a device name and unit number. Once the device name and unit number 188are determined, a lookup is performed to determine the passthrough device 189that corresponds to the given device. 190.Fn cam_open_device 191is rather simple to use, but it isn't really suitable for general use 192because its behavior isn't necessarily deterministic. Programmers writing 193new applications should make the extra effort to use one of the other open 194routines documented below. 195.Pp 196.Fn cam_open_spec_device 197opens the 198.Xr pass 4 199device that corresponds to the device name and unit number passed in. The 200.Ar flags 201should be flags suitable for passing to 202.Xr open 2 . 203The 204.Ar device 205argument is optional. The user may supply pre-allocated space for the 206.Va cam_device 207structure. If the 208.Ar device 209argument is 210.Va NULL , 211.Fn cam_open_spec_device 212will allocate space for the 213.Va cam_device 214structure using 215.Xr malloc 3 . 216.Pp 217.Fn cam_open_btl 218is similar to 219.Fn cam_open_spec_device , 220except that it takes a 221.Tn SCSI 222bus, target and logical unit instead of a device name and unit number as 223arguments. The 224.Va path_id 225argument is the CAM equivalent of a 226.Tn SCSI 227bus number. It represents the logical bus number in the system. The 228.Ar flags 229should be flags suitable for passing to 230.Xr open 2 . 231As with 232.Fn cam_open_spec_device , 233the 234.Fa device 235argument is optional. 236.Pp 237.Fn cam_open_pass 238takes as an argument the 239.Fa path 240of a 241.Xr pass 4 242device to open. No translation or lookup is performed, so the path passed 243in must be that of a CAM 244.Xr pass 4 245device. The 246.Fa flags 247should be flags suitable for passing to 248.Xr open 2 . 249The 250.Fa device 251argument, as with 252.Fn cam_open_spec_device 253and 254.Fn cam_open_btl , 255should be NULL if the user wants the CAM library to allocate space for the 256.Va cam_device 257structure. 258.Fn cam_close_device 259frees the 260.Va cam_device 261structure allocated by one of the above open() calls, and closes the file 262descriptor to the passthrough device. This routine should not be called if 263the user allocated space for the 264.Va cam_device 265structure. Instead, the user should call 266.Fn cam_close_spec_device . 267.Pp 268.Fn cam_close_spec_device 269merely closes the file descriptor opened in one of the open() routines 270described above. This function should be called when the 271.Va cam_device 272structure was allocated by the caller, rather than the CAM library. 273.Pp 274.Fn cam_getccb 275allocates a CCB 276using 277.Xr malloc 3 278and sets fields in the CCB header using values from the 279.Va cam_device 280structure. 281.Pp 282.Fn cam_send_ccb 283sends the given 284.Va ccb 285to the 286.Fa device 287described in the 288.Va cam_device 289structure. 290.Pp 291.Fn cam_freeccb 292frees CCBs allocated by 293.Fn cam_getccb . 294.Pp 295.Fn cam_path_string 296takes as arguments a 297.Va cam_device 298structure, and a string with length 299.Fa len . 300It creates a colon-terminated printing prefix string similar to the ones 301used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". 302.Fn cam_path_string 303will place at most 304.Fa len Ns \-1 305characters into 306.Ar str . 307The 308.Ar len Ns 'th 309character will be the terminating 310.Ql \e0 . 311.Pp 312.Fn cam_device_dup 313operates in a fashion similar to 314.Xr strdup 3 . 315It allocates space for a 316.Va cam_device 317structure and copies the contents of the passed-in 318.Fa device 319structure to the newly allocated structure. 320.Pp 321.Fn cam_device_copy 322copies the 323.Fa src 324structure to 325.Fa dst . 326.Pp 327.Fn cam_get_device 328takes a 329.Fa path 330argument containing a string with a device name followed by a unit number. 331It then breaks the string down into a device name and unit number, and 332passes them back in 333.Fa dev_name 334and 335.Fa unit , 336respectively. 337.Fn cam_get_device 338can 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 349is provided as a convenience function for applications that need to provide 350functionality similar to 351.Fn cam_open_device . 352Programmers are encouraged to use more deterministic methods of obtaining 353device 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 , 358and 359.Fn cam_open_pass 360return a pointer to a 361.Va cam_device 362structure, or NULL if there was an error. 363.Pp 364.Fn cam_getccb 365returns an allocated and partially initialized CCB, or NULL if allocation 366of the CCB failed. 367.Pp 368.Fn cam_send_ccb 369returns a value of -1 if an error occurred, and 370.Va errno 371is set to indicate the error. 372.Pp 373.Fn cam_path_string 374returns a filled printing prefix string as a convenience. This is the same 375.Fa str 376that is passed into 377.Fn cam_path_string . 378.Pp 379.Fn cam_device_dup 380returns a copy of the 381.Va device 382passed in, or NULL if an error occurred. 383.Pp 384.Fn cam_get_device 385returns 0 for success, and -1 to indicate failure. 386.Pp 387If an error is returned from one of the base CAM library functions 388described here, the reason for the error is generally printed in the global 389string 390.Va cam_errbuf 391which is 392.Dv CAM_ERRBUF_SIZE 393characters long. 394.Sh SEE ALSO 395.Xr cam_cdbparse 3 , 396.Xr pass 4 , 397.Xr camcontrol 8 398.Sh HISTORY 399The 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 405doesn't check to see if the 406.Fa path 407passed in is a symlink to something. It also doesn't check to see if the 408.Fa path 409passed in is an actual 410.Xr pass 4 411device. The former would be rather easy to implement, but the latter would 412require a definitive way to identify a device node as a 413.Xr pass 4 414device. 415.Pp 416Some of the functions are possibly mis-named or poorly named. 417