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$ 29.\" 30.Dd October 10, 1998 31.Os 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 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 123The CAM library consists of a number of functions designed to aid in 124programming with the CAM subsystem. 125This man page covers the basic set of 126library functions. 127More functions are documented in the man pages listed 128below. 129.Pp 130Many of the CAM library functions use the 131.Va cam_device 132structure: 133.Bd -literal 134struct cam_device { 135 char device_path[MAXPATHLEN+1];/* 136 * Pathname of the 137 * device given by the 138 * user. This may be 139 * null if the user 140 * states the device 141 * name and unit number 142 * separately. 143 */ 144 char given_dev_name[DEV_IDLEN+1];/* 145 * Device name given by 146 * the user. 147 */ 148 u_int32_t given_unit_number; /* 149 * Unit number given by 150 * the user. 151 */ 152 char device_name[DEV_IDLEN+1];/* 153 * Name of the device, 154 * e.g. 'pass' 155 */ 156 u_int32_t dev_unit_num; /* Unit number of the passthrough 157 * device associated with this 158 * particular device. 159 */ 160 161 char sim_name[SIM_IDLEN+1];/* 162 * Controller name, e.g.'ahc' 163 */ 164 u_int32_t sim_unit_number; /* Controller unit number */ 165 u_int32_t bus_id; /* Controller bus number */ 166 lun_id_t target_lun; /* Logical Unit Number */ 167 target_id_t target_id; /* Target ID */ 168 path_id_t path_id; /* System SCSI bus number */ 169 u_int16_t pd_type; /* type of peripheral device */ 170 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ 171 u_int8_t serial_num[252]; /* device serial number */ 172 u_int8_t serial_num_len; /* length of the serial number */ 173 u_int8_t sync_period; /* Negotiated sync period */ 174 u_int8_t sync_offset; /* Negotiated sync offset */ 175 u_int8_t bus_width; /* Negotiated bus width */ 176 int fd; /* file descriptor for device */ 177}; 178.Ed 179.Pp 180.Fn cam_open_device 181takes as arguments a string describing the device it is to open, and 182.Ar flags 183suitable for passing to 184.Xr open 2 . 185The "path" passed in may actually be most any type of string that contains 186a device name and unit number to be opened. 187The string will be parsed by 188.Fn cam_get_device 189into a device name and unit number. 190Once the device name and unit number 191are determined, a lookup is performed to determine the passthrough device 192that corresponds to the given device. 193.Fn cam_open_device 194is rather simple to use, but it is not really suitable for general use 195because its behavior is not necessarily deterministic. 196Programmers writing 197new applications should make the extra effort to use one of the other open 198routines documented below. 199.Pp 200.Fn cam_open_spec_device 201opens the 202.Xr pass 4 203device that corresponds to the device name and unit number passed in. 204The 205.Ar flags 206should be flags suitable for passing to 207.Xr open 2 . 208The 209.Ar device 210argument is optional. 211The user may supply pre-allocated space for the 212.Va cam_device 213structure. 214If the 215.Ar device 216argument is 217.Va NULL , 218.Fn cam_open_spec_device 219will allocate space for the 220.Va cam_device 221structure using 222.Xr malloc 3 . 223.Pp 224.Fn cam_open_btl 225is similar to 226.Fn cam_open_spec_device , 227except that it takes a 228.Tn SCSI 229bus, target and logical unit instead of a device name and unit number as 230arguments. 231The 232.Va path_id 233argument is the CAM equivalent of a 234.Tn SCSI 235bus number. 236It represents the logical bus number in the system. 237The 238.Ar flags 239should be flags suitable for passing to 240.Xr open 2 . 241As with 242.Fn cam_open_spec_device , 243the 244.Fa device 245argument is optional. 246.Pp 247.Fn cam_open_pass 248takes as an argument the 249.Fa path 250of a 251.Xr pass 4 252device to open. 253No translation or lookup is performed, so the path passed 254in must be that of a CAM 255.Xr pass 4 256device. 257The 258.Fa flags 259should be flags suitable for passing to 260.Xr open 2 . 261The 262.Fa device 263argument, as with 264.Fn cam_open_spec_device 265and 266.Fn cam_open_btl , 267should be NULL if the user wants the CAM library to allocate space for the 268.Va cam_device 269structure. 270.Fn cam_close_device 271frees the 272.Va cam_device 273structure allocated by one of the above open() calls, and closes the file 274descriptor to the passthrough device. 275This routine should not be called if 276the user allocated space for the 277.Va cam_device 278structure. 279Instead, the user should call 280.Fn cam_close_spec_device . 281.Pp 282.Fn cam_close_spec_device 283merely closes the file descriptor opened in one of the open() routines 284described above. 285This function should be called when the 286.Va cam_device 287structure was allocated by the caller, rather than the CAM library. 288.Pp 289.Fn cam_getccb 290allocates a CCB 291using 292.Xr malloc 3 293and sets fields in the CCB header using values from the 294.Va cam_device 295structure. 296.Pp 297.Fn cam_send_ccb 298sends the given 299.Va ccb 300to the 301.Fa device 302described in the 303.Va cam_device 304structure. 305.Pp 306.Fn cam_freeccb 307frees CCBs allocated by 308.Fn cam_getccb . 309.Pp 310.Fn cam_path_string 311takes as arguments a 312.Va cam_device 313structure, and a string with length 314.Fa len . 315It creates a colon-terminated printing prefix string similar to the ones 316used by the kernel. 317e.g.: "(cd0:ahc1:0:4:0): ". 318.Fn cam_path_string 319will place at most 320.Fa len Ns \-1 321characters into 322.Ar str . 323The 324.Ar len Ns 'th 325character will be the terminating 326.Ql \e0 . 327.Pp 328.Fn cam_device_dup 329operates in a fashion similar to 330.Xr strdup 3 . 331It allocates space for a 332.Va cam_device 333structure and copies the contents of the passed-in 334.Fa device 335structure to the newly allocated structure. 336.Pp 337.Fn cam_device_copy 338copies the 339.Fa src 340structure to 341.Fa dst . 342.Pp 343.Fn cam_get_device 344takes a 345.Fa path 346argument containing a string with a device name followed by a unit number. 347It then breaks the string down into a device name and unit number, and 348passes them back in 349.Fa dev_name 350and 351.Fa unit , 352respectively. 353.Fn cam_get_device 354can 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 365is provided as a convenience function for applications that need to provide 366functionality similar to 367.Fn cam_open_device . 368Programmers are encouraged to use more deterministic methods of obtaining 369device 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 , 374and 375.Fn cam_open_pass 376return a pointer to a 377.Va cam_device 378structure, or NULL if there was an error. 379.Pp 380.Fn cam_getccb 381returns an allocated and partially initialized CCB, or NULL if allocation 382of the CCB failed. 383.Pp 384.Fn cam_send_ccb 385returns a value of -1 if an error occured, and 386.Va errno 387is set to indicate the error. 388.Pp 389.Fn cam_path_string 390returns a filled printing prefix string as a convenience. 391This is the same 392.Fa str 393that is passed into 394.Fn cam_path_string . 395.Pp 396.Fn cam_device_dup 397returns a copy of the 398.Va device 399passed in, or NULL if an error occurred. 400.Pp 401.Fn cam_get_device 402returns 0 for success, and -1 to indicate failure. 403.Pp 404If an error is returned from one of the base CAM library functions 405described here, the reason for the error is generally printed in the global 406string 407.Va cam_errbuf 408which is 409.Dv CAM_ERRBUF_SIZE 410characters long. 411.Sh SEE ALSO 412.Xr cam_cdbparse 3 , 413.Xr pass 4 , 414.Xr camcontrol 8 415.Sh HISTORY 416The CAM library first appeared in 417.Fx 3.0 . 418.Sh AUTHORS 419.An Kenneth Merry Aq ken@FreeBSD.org 420.Sh BUGS 421.Fn cam_open_device 422does not check to see if the 423.Fa path 424passed in is a symlink to something. 425It also does not check to see if the 426.Fa path 427passed in is an actual 428.Xr pass 4 429device. 430The former would be rather easy to implement, but the latter would 431require a definitive way to identify a device node as a 432.Xr pass 4 433device. 434.Pp 435Some of the functions are possibly mis-named or poorly named. 436