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.\" $Id$ 29.\" 30.Dd October 10, 1998 31.Os FreeBSD 3.0 32.Dt CAM 3 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 SYNOPSIS 49.Fd #include <camlib.h> 50.Ft struct cam_device * 51.Fo cam_open_device 52.Fa "const char *path" 53.Fa "int flags" 54.Fc 55.Ft struct cam_device * 56.Fo cam_open_spec_device 57.Fa "const char *dev_name" 58.Fa "int unit" 59.Fa "int flags" 60.Fa "struct cam_device *device" 61.Fc 62.Ft struct cam_device * 63.Fo cam_open_btl 64.Fa "path_id_t path_id" 65.Fa "target_id_t target_id" 66.Fa "lun_id_t target_lun" 67.Fa "int flags" 68.Fa "struct cam_device *device" 69.Fc 70.Ft struct cam_device * 71.Fo cam_open_pass 72.Fa "const char *path" 73.Fa "int flags" 74.Fa "struct cam_device *device" 75.Fc 76.Ft void 77.Fo cam_close_device 78.Fa "struct cam_device *dev" 79.Fc 80.Ft void 81.Fo cam_close_spec_device 82.Fa "struct cam_device *dev" 83.Fc 84.Ft union ccb * 85.Fo cam_getccb 86.Fa "struct cam_device *dev" 87.Fc 88.Ft int 89.Fo cam_send_ccb 90.Fa "struct cam_device *device" 91.Fa "union ccb *ccb" 92.Fc 93.Ft void 94.Fo cam_freeccb 95.Fa "union ccb *ccb" 96.Fc 97.Ft char * 98.Fo cam_path_string 99.Fa "struct cam_device *dev" 100.Fa "char *str" 101.Fa "int len" 102.Fc 103.Ft struct cam_device * 104.Fo cam_device_dup 105.Fa "struct cam_device *device" 106.Fc 107.Ft void 108.Fo cam_device_copy 109.Fa "struct cam_device *src" 110.Fa "struct cam_device *dst" 111.Fc 112.Ft int 113.Fo cam_get_device 114.Fa "const char *path" 115.Fa "char *dev_name" 116.Fa "int devnamelen" 117.Fa "int *unit" 118.Fc 119.Sh DESCRIPTION 120The CAM library consists of a number of functions designed to aid in 121programming with the CAM subsystem. This man page covers the basic set of 122library functions. More functions are documented in the man pages listed 123below. 124.Pp 125Many of the CAM library functions use the 126.Va cam_device 127structure: 128.Bd -literal 129struct cam_device { 130 char device_path[MAXPATHLEN+1];/* 131 * Pathname of the 132 * device given by the 133 * user. This may be 134 * null if the user 135 * states the device 136 * name and unit number 137 * separately. 138 */ 139 char given_dev_name[DEV_IDLEN+1];/* 140 * Device name given by 141 * the user. 142 */ 143 u_int32_t given_unit_number; /* 144 * Unit number given by 145 * the user. 146 */ 147 char device_name[DEV_IDLEN+1];/* 148 * Name of the device, 149 * e.g. 'pass' 150 */ 151 u_int32_t dev_unit_num; /* Unit number of the passthrough 152 * device associated with this 153 * particular device. 154 */ 155 156 char sim_name[SIM_IDLEN+1];/* 157 * Controller name, e.g.'ahc' 158 */ 159 u_int32_t sim_unit_number; /* Controller unit number */ 160 u_int32_t bus_id; /* Controller bus number */ 161 lun_id_t target_lun; /* Logical Unit Number */ 162 target_id_t target_id; /* Target ID */ 163 path_id_t path_id; /* System SCSI bus number */ 164 u_int16_t pd_type; /* type of peripheral device */ 165 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ 166 u_int8_t serial_num[252]; /* device serial number */ 167 u_int8_t serial_num_len; /* length of the serial number */ 168 u_int8_t sync_period; /* Negotiated sync period */ 169 u_int8_t sync_offset; /* Negotiated sync offset */ 170 u_int8_t bus_width; /* Negotiated bus width */ 171 int fd; /* file descriptor for device */ 172}; 173.Ed 174.Pp 175.Fn cam_open_device 176takes as arguments a string describing the device it is to open, and 177.Ar flags 178suitable for passing to 179.Xr open 2 . 180The "path" passed in may actually be most any type of string that contains 181a device name and unit number to be opened. The string will be parsed by 182.Fn cam_get_device 183into a device name and unit number. Once the device name and unit number 184are determined, a lookup is performed to determine the passthrough device 185that corresponds to the given device. 186.Fn cam_open_device 187is rather simple to use, but it isn't really suitable for general use 188because its behavior isn't necessarily deterministic. Programmers writing 189new applications should make the extra effort to use one of the other open 190routines documented below. 191.Pp 192.Fn cam_open_spec_device 193opens the 194.Xr pass 4 195device that corresponds to the device name and unit number passed in. The 196.Ar flags 197should be flags suitable for passing to 198.Xr open 2 . 199The 200.Ar device 201argument is optional. The user may supply pre-allocated space for the 202.Va cam_device 203structure. If the 204.Ar device 205argument is 206.Va NULL , 207.Fn cam_open_spec_device 208will allocate space for the 209.Va cam_device 210structure using 211.Xr malloc 3 . 212.Pp 213.Fn cam_open_btl 214is similar to 215.Fn cam_open_spec_device , 216except that it takes a 217.Tn SCSI 218bus, target and logical unit instead of a device name and unit number as 219arguments. The 220.Va path_id 221argument is the CAM equivalent of a 222.Tn SCSI 223bus number. It represents the logical bus number in the system. The 224.Ar flags 225should be flags suitable for passing to 226.Xr open 2 . 227As with 228.Fn cam_open_spec_device , 229the 230.Fa device 231argument is optional. 232.Pp 233.Fn cam_open_pass 234takes as an argument the 235.Fa path 236of a 237.Xr pass 4 238device to open. No translation or lookup is performed, so the path passed 239in must be that of a CAM 240.Xr pass 4 241device. The 242.Fa flags 243should be flags suitable for passing to 244.Xr open 2 . 245The 246.Fa device 247argument, as with 248.Fn cam_open_spec_device 249and 250.Fn cam_open_btl , 251should be NULL if the user wants the CAM library to allocate space for the 252.Va cam_device 253structure. 254.Fn cam_close_device 255frees the 256.Va cam_device 257structure allocated by one of the above open() calls, and closes the file 258descriptor to the passthrough device. This routine should not be called if 259the user allocated space for the 260.Va cam_device 261structure. Instead, the user should call 262.Fn cam_close_spec_device . 263.Pp 264.Fn cam_close_spec_device 265merely closes the file descriptor opened in one of the open() routines 266described above. This function should be called when the 267.Va cam_device 268structure was allocated by the caller, rather than the CAM library. 269.Pp 270.Fn cam_getccb 271allocates a CCB (see 272.Xr ccb 4 ) 273using 274.Xr malloc 3 275and sets fields in the CCB header using values from the 276.Va cam_device 277structure. 278.Pp 279.Fn cam_send_ccb 280sends the given 281.Va ccb 282to the 283.Fa device 284described in the 285.Va cam_device 286structure. 287.Pp 288.Fn cam_freeccb 289frees CCBs allocated by 290.Fn cam_getccb . 291.Pp 292.Fn cam_path_string 293takes as arguments a 294.Va cam_device 295structure, and a string with length 296.Fa len . 297It creates a colon-terminated printing prefix string similar to the ones 298used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". 299.Fn cam_path_string 300will place at most 301.Fa len Ns \-1 302characters into 303.Ar str . 304The 305.Ar len Ns 'th 306character will be the terminating 307.Ql \e0 . 308.Pp 309.Fn cam_device_dup 310operates in a fashion similar to 311.Xr strdup 3 . 312It allocates space for a 313.Va cam_device 314structure and copies the contents of the passed-in 315.Fa device 316structure to the newly allocated structure. 317.Pp 318.Fn cam_device_copy 319copies the 320.Fa src 321structure to 322.Fa dst . 323.Pp 324.Fn cam_get_device 325takes a 326.Fa path 327argument containing a string with a device name followed by a unit number. 328It then breaks the string down into a device name and unit number, and 329passes them back in 330.Fa dev_name 331and 332.Fa unit , 333respectively. 334.Fn cam_get_device 335can handle strings of the following forms, at least: 336.Pp 337.Bl -tag -width 1234 -compact 338.It /dev/foo0a 339.It /dev/rfoo0a 340.It /dev/rfoo1s2c 341.It foo0 342.It foo0a 343.It rfoo0 344.It rfoo0a 345.It nrfoo0 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 occured, 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