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