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 November 23, 2020 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 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 uint32_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 uint32_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 uint32_t sim_unit_number; /* Controller unit number */ 165 uint32_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 uint16_t pd_type; /* type of peripheral device */ 170 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ 171 uint8_t serial_num[252]; /* device serial number */ 172 uint8_t serial_num_len; /* length of the serial number */ 173 uint8_t sync_period; /* Negotiated sync period */ 174 uint8_t sync_offset; /* Negotiated sync offset */ 175 uint8_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.Pp 194.Fn cam_open_spec_device 195opens the 196.Xr pass 4 197device that corresponds to the device name and unit number passed in. 198The 199.Ar flags 200should be flags suitable for passing to 201.Xr open 2 . 202The 203.Ar device 204argument is optional. 205The user may supply pre-allocated space for the 206.Va cam_device 207structure. 208If the 209.Ar device 210argument is 211.Dv NULL , 212.Fn cam_open_spec_device 213will allocate space for the 214.Va cam_device 215structure using 216.Xr malloc 3 . 217.Pp 218.Fn cam_open_btl 219is similar to 220.Fn cam_open_spec_device , 221except that it takes a SCSI bus, 222target and logical unit instead of a device name and unit number as 223arguments. 224The 225.Va path_id 226argument is the CAM equivalent of a SCSI bus number. 227It represents the logical bus number in the system. 228The 229.Ar flags 230should be flags suitable for passing to 231.Xr open 2 . 232As with 233.Fn cam_open_spec_device , 234the 235.Fa device 236argument is optional. 237.Pp 238.Fn cam_open_pass 239takes as an argument the 240.Fa path 241of a 242.Xr pass 4 243device to open. 244No translation or lookup is performed, so the path passed 245in must be that of a CAM 246.Xr pass 4 247device. 248The 249.Fa flags 250should be flags suitable for passing to 251.Xr open 2 . 252The 253.Fa device 254argument, as with 255.Fn cam_open_spec_device 256and 257.Fn cam_open_btl , 258should be 259.Dv NULL 260if the user wants the CAM library to allocate space for the 261.Va cam_device 262structure. 263.Pp 264.Fn cam_close_device 265frees the 266.Va cam_device 267structure allocated by one of the above 268.Xr open 2 269calls, and closes the file 270descriptor to the passthrough device. 271This routine should not be called if 272the user allocated space for the 273.Va cam_device 274structure. 275Instead, the user should call 276.Fn cam_close_spec_device . 277.Pp 278.Fn cam_close_spec_device 279merely closes the file descriptor opened in one of the 280.Xr open 2 281routines 282described above. 283This function should be called when the 284.Va cam_device 285structure was allocated by the caller, rather than the CAM library. 286.Pp 287.Fn cam_getccb 288allocates a prezeroed CCB 289using 290.Xr calloc 3 291and sets fields in the CCB header using values from the 292.Va cam_device 293structure. 294.Pp 295.Fn cam_send_ccb 296sends the given 297.Va ccb 298to the 299.Fa device 300described in the 301.Va cam_device 302structure. 303.Pp 304.Fn cam_freeccb 305frees CCBs allocated by 306.Fn cam_getccb . 307If 308.Va ccb 309is 310.Dv NULL , 311no action is taken. 312.Pp 313.Fn cam_path_string 314takes as arguments a 315.Va cam_device 316structure, and a string with length 317.Fa len . 318It creates a colon-terminated printing prefix string similar to the ones 319used by the kernel. 320e.g.: "(cd0:ahc1:0:4:0): ". 321.Fn cam_path_string 322will place at most 323.Fa len Ns \-1 324characters into 325.Ar str . 326The 327.Ar len Ns 'th 328character will be the terminating 329.Ql \e0 . 330.Pp 331.Fn cam_device_dup 332operates in a fashion similar to 333.Xr strdup 3 . 334It allocates space for a 335.Va cam_device 336structure and copies the contents of the passed-in 337.Fa device 338structure to the newly allocated structure. 339.Pp 340.Fn cam_device_copy 341copies the 342.Fa src 343structure to 344.Fa dst . 345.Pp 346.Fn cam_get_device 347takes a 348.Fa path 349argument containing a string with a device name followed by a unit number. 350It then breaks the string down into a device name and unit number, and 351passes them back in 352.Fa dev_name 353and 354.Fa unit , 355respectively. 356.Fn cam_get_device 357can handle strings of the following forms, at least: 358.Pp 359.Bl -tag -width 1234 -compact 360.It /dev/foo1 361.It foo0 362.It nsa2 363.El 364.Pp 365.Fn cam_get_device 366is provided as a convenience function for applications that need to provide 367functionality similar to 368.Fn cam_open_device . 369.Sh RETURN VALUES 370.Fn cam_open_device , 371.Fn cam_open_spec_device , 372.Fn cam_open_btl , 373and 374.Fn cam_open_pass 375return a pointer to a 376.Va cam_device 377structure, or 378.Dv NULL 379if there was an error. 380.Pp 381.Fn cam_getccb 382returns an allocated and partially initialized CCB, or 383.Dv NULL 384if allocation of the CCB failed. 385.Pp 386.Fn cam_send_ccb 387returns a value of -1 if an error occurred, and 388.Va errno 389is set to indicate the error. 390.Pp 391.Fn cam_path_string 392returns a filled printing prefix string as a convenience. 393This is the same 394.Fa str 395that is passed into 396.Fn cam_path_string . 397.Pp 398.Fn cam_device_dup 399returns a copy of the 400.Va device 401passed in, or 402.Dv NULL 403if an error occurred. 404.Pp 405.Fn cam_get_device 406returns 0 for success, and -1 to indicate failure. 407.Pp 408If an error is returned from one of the base CAM library functions 409described here, the reason for the error is generally printed in the global 410string 411.Va cam_errbuf 412which is 413.Dv CAM_ERRBUF_SIZE 414characters long. 415.Sh SEE ALSO 416.Xr cam_cdbparse 3 , 417.Xr pass 4 , 418.Xr camcontrol 8 419.Sh HISTORY 420The CAM library first appeared in 421.Fx 3.0 . 422.Sh AUTHORS 423.An Kenneth Merry Aq Mt ken@FreeBSD.org 424.Sh BUGS 425.Fn cam_open_device 426does not check to see if the 427.Fa path 428passed in is a symlink to something. 429It also does not check to see if the 430.Fa path 431passed in is an actual 432.Xr pass 4 433device. 434The former would be rather easy to implement, but the latter would 435require a definitive way to identify a device node as a 436.Xr pass 4 437device. 438.Pp 439Some of the functions are possibly misnamed or poorly named. 440