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.Dd June 1, 2023 29.Dt CAM 3 30.Os 31.Sh NAME 32.Nm cam_open_device , 33.Nm cam_open_spec_device , 34.Nm cam_open_btl , 35.Nm cam_open_pass , 36.Nm cam_close_device , 37.Nm cam_close_spec_device , 38.Nm cam_getccb , 39.Nm cam_send_ccb , 40.Nm cam_freeccb , 41.Nm cam_path_string , 42.Nm cam_device_dup , 43.Nm cam_device_copy , 44.Nm cam_get_device 45.Nd CAM user library 46.Sh LIBRARY 47.Lb libcam 48.Sh SYNOPSIS 49.In stdio.h 50.In camlib.h 51.Ft struct cam_device * 52.Fo cam_open_device 53.Fa "const char *path" 54.Fa "int flags" 55.Fc 56.Ft struct cam_device * 57.Fo cam_open_spec_device 58.Fa "const char *dev_name" 59.Fa "int unit" 60.Fa "int flags" 61.Fa "struct cam_device *device" 62.Fc 63.Ft struct cam_device * 64.Fo cam_open_btl 65.Fa "path_id_t path_id" 66.Fa "target_id_t target_id" 67.Fa "lun_id_t target_lun" 68.Fa "int flags" 69.Fa "struct cam_device *device" 70.Fc 71.Ft struct cam_device * 72.Fo cam_open_pass 73.Fa "const char *path" 74.Fa "int flags" 75.Fa "struct cam_device *device" 76.Fc 77.Ft void 78.Fo cam_close_device 79.Fa "struct cam_device *dev" 80.Fc 81.Ft void 82.Fo cam_close_spec_device 83.Fa "struct cam_device *dev" 84.Fc 85.Ft union ccb * 86.Fo cam_getccb 87.Fa "struct cam_device *dev" 88.Fc 89.Ft int 90.Fo cam_send_ccb 91.Fa "struct cam_device *device" 92.Fa "union ccb *ccb" 93.Fc 94.Ft void 95.Fo cam_freeccb 96.Fa "union ccb *ccb" 97.Fc 98.Ft char * 99.Fo cam_path_string 100.Fa "struct cam_device *dev" 101.Fa "char *str" 102.Fa "int len" 103.Fc 104.Ft struct cam_device * 105.Fo cam_device_dup 106.Fa "struct cam_device *device" 107.Fc 108.Ft void 109.Fo cam_device_copy 110.Fa "struct cam_device *src" 111.Fa "struct cam_device *dst" 112.Fc 113.Ft int 114.Fo cam_get_device 115.Fa "const char *path" 116.Fa "char *dev_name" 117.Fa "int devnamelen" 118.Fa "int *unit" 119.Fc 120.Sh DESCRIPTION 121The CAM library consists of a number of functions designed to aid in 122programming with the CAM subsystem described in 123.Xr cam 4 . 124This man page covers the basic set of 125library functions. 126More 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 uint32_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 uint32_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 uint32_t sim_unit_number; /* Controller unit number */ 164 uint32_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 uint16_t pd_type; /* type of peripheral device */ 169 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ 170 uint8_t serial_num[252]; /* device serial number */ 171 uint8_t serial_num_len; /* length of the serial number */ 172 uint8_t sync_period; /* Negotiated sync period */ 173 uint8_t sync_offset; /* Negotiated sync offset */ 174 uint8_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. 186The string will be parsed by 187.Fn cam_get_device 188into a device name and unit number. 189Once the device name and unit number 190are determined, a lookup is performed to determine the passthrough device 191that corresponds to the given device. 192.Pp 193.Fn cam_open_spec_device 194opens the 195.Xr pass 4 196device that corresponds to the device name and unit number passed in. 197The 198.Ar flags 199should be flags suitable for passing to 200.Xr open 2 . 201The 202.Ar device 203argument is optional. 204The user may supply pre-allocated space for the 205.Va cam_device 206structure. 207If the 208.Ar device 209argument is 210.Dv 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 SCSI bus, 221target and logical unit instead of a device name and unit number as 222arguments. 223The 224.Va path_id 225argument is the CAM equivalent of a SCSI bus number. 226It represents the logical bus number in the system. 227The 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. 243No translation or lookup is performed, so the path passed 244in must be that of a CAM 245.Xr pass 4 246device. 247The 248.Fa flags 249should be flags suitable for passing to 250.Xr open 2 . 251The 252.Fa device 253argument, as with 254.Fn cam_open_spec_device 255and 256.Fn cam_open_btl , 257should be 258.Dv NULL 259if the user wants the CAM library to allocate space for the 260.Va cam_device 261structure. 262.Pp 263.Fn cam_close_device 264frees the 265.Va cam_device 266structure allocated by one of the above 267.Xr open 2 268calls, and closes the file 269descriptor to the passthrough device. 270This routine should not be called if 271the user allocated space for the 272.Va cam_device 273structure. 274Instead, the user should call 275.Fn cam_close_spec_device . 276.Pp 277.Fn cam_close_spec_device 278merely closes the file descriptor opened in one of the 279.Xr open 2 280routines 281described above. 282This function should be called when the 283.Va cam_device 284structure was allocated by the caller, rather than the CAM library. 285.Pp 286.Fn cam_getccb 287allocates a prezeroed CCB 288using 289.Xr calloc 3 290and sets fields in the CCB header using values from the 291.Va cam_device 292structure. 293.Pp 294.Fn cam_send_ccb 295sends the given 296.Va ccb 297to the 298.Fa device 299described in the 300.Va cam_device 301structure. 302.Pp 303.Fn cam_freeccb 304frees CCBs allocated by 305.Fn cam_getccb . 306If 307.Va ccb 308is 309.Dv NULL , 310no action is taken. 311.Pp 312.Fn cam_path_string 313takes as arguments a 314.Va cam_device 315structure, and a string with length 316.Fa len . 317It creates a colon-terminated printing prefix string similar to the ones 318used by the kernel. 319e.g.: "(cd0:ahc1:0:4:0): ". 320.Fn cam_path_string 321will place at most 322.Fa len Ns \-1 323characters into 324.Ar str . 325The 326.Ar len Ns 'th 327character will be the terminating 328.Ql \e0 . 329.Pp 330.Fn cam_device_dup 331operates in a fashion similar to 332.Xr strdup 3 . 333It allocates space for a 334.Va cam_device 335structure and copies the contents of the passed-in 336.Fa device 337structure to the newly allocated structure. 338.Pp 339.Fn cam_device_copy 340copies the 341.Fa src 342structure to 343.Fa dst . 344.Pp 345.Fn cam_get_device 346takes a 347.Fa path 348argument containing a string with a device name followed by a unit number. 349It then breaks the string down into a device name and unit number, and 350passes them back in 351.Fa dev_name 352and 353.Fa unit , 354respectively. 355.Fn cam_get_device 356can handle strings of the following forms, at least: 357.Pp 358.Bl -tag -width 1234 -compact 359.It /dev/foo1 360.It foo0 361.It nsa2 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 . 368.Sh RETURN VALUES 369.Fn cam_open_device , 370.Fn cam_open_spec_device , 371.Fn cam_open_btl , 372and 373.Fn cam_open_pass 374return a pointer to a 375.Va cam_device 376structure, or 377.Dv NULL 378if there was an error. 379.Pp 380.Fn cam_getccb 381returns an allocated and partially initialized CCB, or 382.Dv NULL 383if allocation of the CCB failed. 384.Pp 385.Fn cam_send_ccb 386returns a value of -1 if an error occurred, and 387.Va errno 388is set to indicate the error. 389.Pp 390.Fn cam_path_string 391returns a filled printing prefix string as a convenience. 392This is the same 393.Fa str 394that is passed into 395.Fn cam_path_string . 396.Pp 397.Fn cam_device_dup 398returns a copy of the 399.Va device 400passed in, or 401.Dv NULL 402if an error occurred. 403.Pp 404.Fn cam_get_device 405returns 0 for success, and -1 to indicate failure. 406.Pp 407If an error is returned from one of the base CAM library functions 408described here, the reason for the error is generally printed in the global 409string 410.Va cam_errbuf 411which is 412.Dv CAM_ERRBUF_SIZE 413characters long. 414.Sh SEE ALSO 415.Xr cam_cdbparse 3 , 416.Xr pass 4 , 417.Xr camcontrol 8 418.Sh HISTORY 419The CAM library first appeared in 420.Fx 3.0 . 421.Sh AUTHORS 422.An Kenneth Merry Aq Mt ken@FreeBSD.org 423.Sh BUGS 424.Fn cam_open_device 425does not check to see if the 426.Fa path 427passed in is a symlink to something. 428It also does not check to see if the 429.Fa path 430passed in is an actual 431.Xr pass 4 432device. 433The former would be rather easy to implement, but the latter would 434require a definitive way to identify a device node as a 435.Xr pass 4 436device. 437.Pp 438Some of the functions are possibly misnamed or poorly named. 439