CAM(3)

명칭
cam_open_device, cam_open_spec_device, cam_open_btl, cam_open_pass, cam_close_device, cam_close_spec_device, cam_getccb, cam_send_ccb, cam_freeccb, cam_path_string, cam_device_dup, cam_device_copy, cam_get_device - CAM 유저 프로그램 라이브러리

프로그램 라이브러리
libcam

서식
<stdio.h> <camlib.h> struct cam_device * cam_open_device(const char *path, int flags) struct cam_device * cam_open_spec_device(const char *dev_name, int unit, int flags, struct cam_device *device) struct cam_device * cam_open_btl(path_id_t path_id, target_id_t target_id, lun_id_t target_lun, int flags, struct cam_device *device) struct cam_device * cam_open_pass(const char *path, int flags, struct cam_device *device) void cam_close_device(struct cam_device *dev) void cam_close_spec_device(struct cam_device *dev) union ccb * cam_getccb(struct cam_device *dev) int cam_send_ccb(struct cam_device *device, union ccb *ccb) void cam_freeccb(union ccb *ccb) char * cam_path_string(struct cam_device *dev, char *str, int len) struct cam_device * cam_device_dup(struct cam_device *device) void cam_device_copy(struct cam_device *src, struct cam_device *dst) int cam_get_device(const char *path, char *dev_name, int devnamelen, int *unit)

해설
CAM 프로그램 라이브러리는, CAM 시스템에서의 프로그래밍을 보조하는 듯 설계되어 따분한가의 함수로 구성되어 있습니다. 이 메뉴얼 페이지는, 프로그램 라이브러리 함수의 기본 세트에 대해 설명되어 있습니다. 다음에 리스트 한다 메뉴얼 페이지에 한층 더 많은 함수가 기재되어 있습니다.

다수의 CAM 프로그램 라이브러리 함수가 cam_device 구조체를 사용합니다.

    struct cam_device {
    	char		device_path[MAXPATHLEN+1];/*
    						   * 유저가 지정했다
    						   * 디바이스의 패스명.
    						   * 유저가 디바이스명
    						   * (와)과 유니트 번호를
    						   * 따로 따로 기술하면(자)
    						   * 이것은 NULL 에
    						   * 되는 일이 있습니다.
    						   */
    	char		given_dev_name[DEV_IDLEN+1];/*
    						     * 유저가 지정했다
    						     * 디바이스명.
    						     */
    	u_int32_t	given_unit_number;	    /*
    						     * 유저가 지정했다
    						     * 유니트 번호.
    						     */
    	char		device_name[DEV_IDLEN+1];/*
    						  * 디바이스명.
    						  * 예를 들어 'pass'
    						  */
    	u_int32_t	dev_unit_num;	/* 이 특정의 디바이스에
    					 * 대응하는 통과 디바이스의
    					 * 유니트 번호.
    					 */
    	char		sim_name[SIM_IDLEN+1];/*
    					       * 콘트롤러명.
    					       * 예를 들어 'ahc'
    					       */
    	u_int32_t	sim_unit_number; /* 콘트롤러 유니트 번호 */
    	u_int32_t	bus_id;		 /* 콘트롤러 버스 번호 */
    	lun_id_t	target_lun;	 /* 논리 장치 번호 */
    	target_id_t	target_id;	 /* 타겟 ID */
    	path_id_t	path_id;	 /* 시스템 SCSI 버스 번호 */
    	u_int16_t	pd_type;	 /* 주변장치의 타입 */
    	struct scsi_inquiry_data inq_data;  /* SCSI 조회 데이터 */
    	u_int8_t	serial_num[252]; /* 디바이스 시리얼 번호 */
    	u_int8_t	serial_num_len;  /* 시리얼 번호의 길이 */
    	u_int8_t	sync_period;	 /* 조정된 동기 주기 */
    	u_int8_t	sync_offset;     /* 조정된 동기 오프셋(offset) */
    	u_int8_t	bus_width;	 /* 조정된 버스폭 */
    	int		fd;		 /* 디바이스의 파일 기술자 */
    };

cam_open_device() (은)는, 인수로서 열려 하고 있는 디바이스를 기술하는 캐릭터 라인, 및 open(2) 에 건네주는데 적절한 flags (을)를 취합니다. 건네받는 「패스」는, 실제로는, 여는 디바이스명과 유니트 번호가 들어간 임의의 타입의 캐릭터 라인입니다. 캐릭터 라인은 cam_get_device() 에 의해 해석되어, 디바이스명과 유니트 번호가 됩니다. 디바이스명과 유니트 번호가 결정되면(자), look 업이 실행되어, 지정의 디바이스에 대응하는 통과 디바이스를 결정합니다. cam_open_device() (은)는 사용법은 꽤 간단합니다만, 현실에는 일반적인 사용에 적절하고 있지 않습니다. 동작이 반드시 결정적이지 않기 때문입니다. 새로운 어플리케이션을 작성한 프로그래머는, 이하에 설명하는 다른 오픈 routine의 1 개(살)을 사용하도록 해 주세요.

cam_open_spec_device() (은)는, 건네받은 디바이스명과 유니트 번호에 대응한다 pass(4) 디바이스를 엽니다. flags (은)는, open(2) 에 건네주는데 적절한 플래그이다 필요가 있습니다. device 인수는 옵션입니다. 유저는, cam_device 구조체에 할당해 끝난 공간을 지정할 수 있습니다. device 인수가 NULL 의 경우, cam_open_spec_device() (은)는, malloc(3) (을)를 사용해 cam_device 구조 체용의 공간을 할당합니다.

cam_open_btl() (은)는, cam_open_spec_device() 에 유사하고 있습니다만, 인수로서 디바이스명과 유니트 번호 대신에 SCSI 버스, 타겟, 및 논리 유니트를 취하는 점이 다릅니다. path_id 인수는, SCSI 버스 번호의 CAM 의 동등의 것입니다. 이것은 시스템내의 논리 버스 번호를 나타냅니다. flags (은)는, open(2) 에 건네주는데 적절한 플래그일 필요가 있습니다. cam_open_spec_device() (와)과 같이, device 인수는 옵션입니다.

cam_open_pass() (은)는, 인수로서 연다 pass(4) 디바이스의 path (을)를 취합니다. 변환도 look 업도 행해지지 않기 때문에, 건네받는 패스는 CAM pass(4) 디바이스의 패스가 아니면 안됩니다. flags (은)는, open(2) 에 건네주는데 적합한 플래그이다 필요가 있습니다. device 인수는, 유저가 CAM 프로그램 라이브러리에 cam_device 구조 체용의 공간을 할당해 시키고 싶은 경우는, cam_open_spec_device() 및 cam_open_btl() (와)과 같이, NULL 일 필요가 있습니다. cam_close_device() (은)는, 상기의 open() 호출의 1 개(살)이 할당했다 cam_device 구조체를 해방해, 통과 디바이스에의 파일 기술자를 닫습니다. 유저가 cam_device 구조 체용의 공간을 할당하고 있는 경우는, 이 routine를 불러 내 되지 않습니다. 대신에, 유저는 cam_close_spec_device() (을)를 호출해야 합니다.

cam_close_spec_device() (은)는, 상기의 open() routine의 1 개(살)로 열렸다 파일 기술자를 닫을 뿐입니다. 이 함수는, cam_device 하지만 CAM 프로그램 라이브러리 (이)가 아니고, 호출 바탕으로야는 할당해졌을 때에 호출할 필요가 있습니다.

cam_getccb() (은)는, malloc(3) (을)를 사용해 CCB (을)를 할당해, cam_device 구조의 값을 사용해 CCB 헤더내에 필드를 설정합니다.

cam_send_ccb() (은)는, 지정의 ccb (을)를, cam_device 구조 체내에서 기술되었다 device 에 송신합니다.

cam_freeccb() (은)는, cam_getccb() 하지만 할당했다 CCB (을)를 해방합니다.

cam_path_string() (은)는, 인수로서 cam_device 구조체, 및 길이가 len 의 string를 취합니다. 이 함수는, 커널이 사용하는 것 과 유사한, 코론으로 종료하는 인쇄 접두어 string를 작성합니다. 예를 들어,"(cd0:ahc1:0:4:0): " 입니다. cam_path_string() (은)는, 많아도 len-1 캐릭터를 str (으)로 설정합니다. len 차례째의 캐릭터는, 종료를 나타낸다 ‘\0’ 입니다.

cam_device_dup() (은)는, strdup(3) (와)과 같이 방법으로 동작합니다. cam_device 구조 체용에 공간을 할당해 건네받았다 device 구조체의 내용을, 새롭게 할당해졌다 구조체에 카피합니다.

cam_device_copy() 하 src 구조체를 dst 에 카피합니다.

cam_get_device() (은)는, 디바이스명에 유니트 번호가 계속된 string가 들어갔다 path 인수를 취합니다. 다음에, string를 디바이스명과 유니트명 으로 분해해, 각각 dev_name (와)과 unit 에 되돌립니다. cam_get_device() (은)는, 적어도 다음의 형식의 string를 처리할 수 있습니다.

/dev/foo0a
/dev/foo1s2c
foo0
foo0a
nfoo0

cam_get_device() (은)는, cam_open_device() 에 유사한 기능을 준비할 필요가 있다 어플리케이션용의 편리한 함수로서 갖춰져 있습니다. 프로그래머는, 가능하면, 디바이스명과 유니트 번호를 얻는 좀 더 결정적인 방식을 사용하는 것을 추천합니다.

반환값
cam_open_device() , cam_open_spec_device() , cam_open_btl() , 및 cam_open_pass() (은)는, cam_device 구조를 가리키는 포인터를 돌려줍니다. 또는, 에러가 있었을 경우는 NULL (을)를 돌려줍니다.

cam_getccb() (은)는, 할당이 끝난 상태로 부분적으로 초기화 끝난 CCB (을)를 돌려줍니다. 또, CCB 의 할당이 처리 실패했을 경우는 NULL (을)를 돌려줍니다.

cam_send_ccb() (은)는, 에러가 발생했을 경우, 값 -1 을 돌려주어, errno 하지만 에러를 가리키도록(듯이) 설정됩니다.

cam_path_string() (은)는, 편의로서 기입된 인쇄 접두어를 돌려줍니다. 이것은, cam_path_string() 에게 건네지는 것과 같다 str 입니다.

cam_device_dup() (은)는, 건네받았다 device 의 카피를 돌려줍니다. 또는, 에러가 발생했을 경우는 NULL (을)를 돌려줍니다.

cam_get_device() (은)는, 처리 성공의 경우는 0 을 돌려주어, 처리 실패를 나타내는 경우는 -1 을 돌려줍니다.

여기서 설명한 기본 CAM 프로그램 라이브러리 함수의 1 개로부터 에러가 돌려주어졌을 경우는, 에러의 이유가 일반적으로 글로벌 string cam_errbuf 에 인쇄됩니다. 이것의 길이는 CAM_ERRBUF_SIZE 캐릭터입니다.

관련 항목
cam_cdbparse(3), pass(4), camcontrol(8)

역사
CAM 프로그램 라이브러리는 FreeBSD 3.0 그리고 처음 등장했습니다.

저자
Kenneth Merry <ken@FreeBSD.org>

버그
cam_open_device() (은)는, 건네받았다 path 하지만 무엇인가에의 symlink 인지 어떤지 체크하지 않습니다. 건네받았다 path 하지만 실제의 pass(4) 디바이스인지 어떤지도 체크하지 않습니다. 전의 체크를 실현하는 것은 꽤 간단하겠지만, 후의 체크를 실행하기 위해서는, pass(4) 디바이스로서 디바이스 노드를 식별한다 결정적인 방법이 필요하겠지요.

아마 함수에는 이름이 부적절한 것이나, 이름이 불충분한 것이 있습니다.