.\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#) dbopen. 3 8.5 (Berkeley) 1/2/94 .\" %FreeBSD: src/lib/libc/db/man/dbopen. 3, v 1.3. 2.2 2001/12/14 18:33:49 ru Exp % .\" $FreeBSD: doc/ja_JP.eucJP/man/man3/dbopen. 3, v 1.4 2002/05/18 07:12:54 horikawa Exp $ .\" .Dd January 2, 1994 .Dt DBOPEN 3 .Os .Sh 명칭 .Nm dbopen .Nd 데이타베이스 액세스 방식 .Sh 서식 .In sys/types.h .In limits.h .In db.h .Ft DB * .Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" .Sh 해설 .Fn dbopen (은)는, 데이타베이스 파일에의 프로그램 라이브러리 인터페이스입니다. 서포트되고 있는 파일 포맷은, btree 형식, 해시 형식, UNIX 파일 지향 형식입니다. btree 포맷은, 정렬 끝난 밸런스를 잡혔다 트리 구조의 표현입니다. 해시 포맷은, 확장 가능하고 동적인 해시 schema입니다. 플랫 파일 포맷은, 고정장 또는 가변장 레코드로부터 되는 바이트 스트림 파일입니다. 포맷 및 파일 포맷에 고유의 정보에 대해서는, 각각의 메뉴얼 페이지에 자세하게 진술되고 있습니다. .Xr btree 3 , .Xr hash 3 , .Xr recno 3 입니다. .Pp .Fn dbopen (은)는, 읽어들여 또는 기입해용으로 .Fa file (을)를 오픈합니다. 디스크상 으로 유지할 필요가 없는 파일은, 파일 파라미터를 .Dv NULL (으)로 설정하는 것으로 작성할 수 있습니다. .Pp 인수 .Fa flags (와)과 인수 .Fa mode (은)는, .Xr open 2 그리고 지정되고 것과 같습니다. 그러나, .Dv O_CREAT , O_EXCL , O_EXLOCK , O_NONBLOCK , .Dv O_RDONLY , O_RDWR , O_SHLOCK , .Dv O_TRUNC 의 각 플래그에만 의미가 있습니다 (데이타베이스 파일은 .Dv O_WRONLY 그럼 오픈할 수 없는 것에 주의해 주세요). .\"Three additional options may be specified by .\".Em or Ns 'ing .\"them into the .\".Fa flags .\"argument. .\".Bl -tag -width indent .\".It Dv DB_LOCK .\"Do the necessary locking in the database to support concurrent access. .\"If concurrent access isn't needed or the database is read-only this .\"flag should not be set, as it tends to have an associated performance .\"penalty. .\".It Dv DB_SHMEM .\"Place the underlying memory pool used by the database in shared .\"memory. .\"Necessary for concurrent access. .\".It Dv DB_TXN .\"Support transactions in the database. .\"The .\".Dv DB_LOCK .\"and .\".Dv DB_SHMEM .\"flags must be set as well. .\".El .Pp 인수 .Fa type (은)는, 타입 .Ft DBTYPE (인클루드 파일 .Aq Pa db.h 그리고 정의되고 있습니다) (이어)여, .Dv DB_BTREE , .Dv DB_HASH , .Dv DB_RECNO (을)를 설정할 수 있습니다. .Pp 인수 .Fa openinfo (은)는, 액세스 방식의 메뉴얼 페이지에 설명되어 있도록(듯이), 액세스 방식으로 고유의 구조를 가리키는 포인터입니다. .Fa openinfo 하지만 .Dv NULL 의 경우, 각 액세스 방식은, 시스템과 액세스 방식으로 적절한 디폴트를 사용합니다. .Pp .Fn dbopen (은)는, 처리가 성공하면(자) .Ft DB 구조체를 가리키는 포인터를 돌려주어, 에러의 경우에는 눌을 돌려줍니다. .Ft DB 구조체는, 인클루드 파일 .Aq Pa db.h 안에 정의되고 있어 적어도 다음의 필드가 포함되어 있습니다. .Bd -literal typedef struct { DBTYPE type; int (*close)(const DB *db); int (*del)(const DB *db, const DBT *key, u_int flags); int (*fd)(const DB *db); int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); int (*put)(const DB *db, DBT *key, const DBT *data, u_int flags); int (*sync)(const DB *db, u_int flags); int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); } DB; .Ed .Pp 이러한 요소는, 데이타베이스 타입과 각종의 액션을 실행한다 함수세트를 기술하고 있습니다. 이러한 함수는, .Fn dbopen 에 의해 돌려주어진 구조체에의 포인터를 인수에 취해, 가끔 키 / 데이터 구조와 플래그치를 가리키는 1 개(살) 또는 복수의 포인터를 취하는 일도 있습니다. .Bl -tag -width indent .It Va type 기본 액세스 방식 ( 및 파일 포맷)의 타입. .It Va close 캐쉬된 정보를 디스크에 플래시 해, 할당해진 리소스를 해방해, 기본으로 되어 있는 파일 (1 개(살) 또는 복수)을 닫는 routine를 가리킨다 포인터. 키 / 데이터의 조는 메모리에 캐쉬되므로, 파일을 .Va close 함수 또는 .Va sync 함수로 파일을 동기 하는데 실패하면(자), 정보에 모순이나 결핍이 생길지도 모릅니다. .Va close routine는, 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려줍니다. .It Va del 키 / 데이터의 조를 데이타베이스로부터 삭제하는 routine를 가리키는 포인터. .Pp 파라미터 .Fa flags (은)는 다음의 값으로 설정할 수 있습니다. .Bl -tag -width indent .It Dv R_CURSOR 커서가 참조하는 레코드를 삭제합니다. 커서는, 미리 초기화해 둘 필요가 있습니다. .El .Pp .Va delete routine는 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려줍니다. 지정했다 .Fa key 하지만 파일안에 없었던 경우는 1 을 돌려줍니다. .It Va fd 기본 데이타베이스의 파일 기술 표현을 돌려주는 routine를 가리키는 포인터. 같은 파일을 참조하고 있는 파일 기술자는, 같다 .Fa file 이름으로 .Fn dbopen (을)를 호출하는 전프로세스에 돌려주어집니다. 이 파일 기술자는, 락 함수 .Xr fcntl 2 (와)과 .Xr flock 2 에의 인수로서 안전하게 사용할 수 있습니다. 파일 기술자는, 반드시 액세스 방식이 사용하고 있는 기본 파일에 관련지을 수 있고 있을 필요는 없습니다. 파일 기술자는 메모리데이타베이스내에서 이용할 수 없습니다. .Va \&fd routine는, 에러 종료시는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 파일 기술자를 돌려줍니다. .It Va get 데이타베이스로부터 키를 사용해 꺼내는 인터페이스이다 routine를 가리키는 포인터. 지정의 .Fa key 에 관련지을 수 있었던 데이터의 주소와 길이가, .Fa data 그리고 참조되는 구조 체내에 돌려주어집니다. .Va get routine는 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려줍니다. .Fa key 하지만 파일안에 없었던 경우는 1 을 돌려줍니다. .It Va put 키 / 데이터의 조를 데이타베이스내에 보존하는 routine를 가리키는 포인터. .Pp 파라미터 .Fa flags 에는 다음의 값의 1 개를 설정할 수 있습니다. .Bl -tag -width indent .It Dv R_CURSOR 커서가 참조하는 키 / 데이터의 조를 옮겨놓습니다. 커서는, 미리 초기화되고 있을 필요가 있습니다. .It Dv R_IAFTER .Fa key 그리고 참조되는 데이터의 직후에 데이터를 추가해, 새로운 키 / 데이터의 조를 작성합니다. 추가한 키 / 데이터의 조의 레코드 번호가 .Fa key 구조 체내에 돌려주어집니다 ( .Dv DB_RECNO 액세스 방식에만 적용할 수 있습니다). .It Dv R_IBEFORE .Fa key 그리고 참조되는 데이터의 직전에 데이터를 삽입해, 새로운 키 / 데이터의 조를 작성합니다. 추가한 키 / 데이터의 조의 레코드 번호가 .Fa key 구조 체내에 돌려주어집니다 ( .Dv DB_RECNO 액세스 방식에만 적용할 수 있습니다). .It Dv R_NOOVERWRITE 키가 그 이전에 존재하지 않는 경우에만, 새로운 키 / 데이터의 조를 입력합니다. .It Dv R_SETCURSOR 키 / 데이터의 조를 보존해, 그것을 참조하는 커서의 위치를 세트, 또는 초기화합니다 ( .Dv DB_BTREE 및 .Dv DB_RECNO 액세스 방식에만 적용할 수 있습니다). .El .Pp .Dv R_SETCURSOR 하지만 이용할 수 있는 것은, .Dv DB_BTREE (와)과 .Dv DB_RECNO 의 액세스 방식에서 뿐입니다. 키에는, 변화하지 않는 고유의 순서가 있는 것을 의미하고 있기 때문입니다. .Pp .Dv R_IAFTER (와)과 .Dv R_IBEFORE 하 .Dv DB_RECNO 액세스 방식에만 이용할 수 있습니다. 모두, 액세스 방식이 새로운 키를 작성할 수 있는 것을 의미하고 있기 때문입니다. 이것은, 키가 순서 붙일 수 있어 있어 독립인 경우에만 진이 됩니다. 예를 들어, 레코드 번호입니다. .Pp .Va put routine의 디폴트의 동작은, 새로운 키/데이터의 조를 입력해, 그 이전에 존재하고 있던 키를 옮겨놓는 것입니다. .Pp .Va put routine는 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려주어, .Dv R_NOOVERWRITE 플래그가 설정되어 있어, 게다가 키가 파일내에 이미 존재하는 경우는 1 을 돌려줍니다. .It Va seq 데이타베이스로부터의 시퀀셜인 취득용 인터페이스이다 routine를 가리키는 포인터. 키의 주소와 길이는 .Fa key 하지만 참조하는 구조 체내에 돌려주어져 데이터의 주소와 길이는 .Fa data 하지만 참조하는 구조 체내에 돌려주어집니다. .Pp 시퀀셜인 키 / 데이터의 조의 취득은, 언제라도 개시할 수가 있어 .Dq 커서 의 위치는 .Va del , .Va get , .Va put , .Va sync 의 각 routine에 의한 호출에 의해 영향을 받지 않습니다. 시퀀셜인 주사의 사이의 데이타베이스의 수정은 주사에 반영됩니다. 즉, 커서의 전에 삽입된 레코드가 돌려주어질 때까지, 커서의 뒤로 삽입된 레코드는 돌려주어지지 않습니다. .Pp .Fa flags 값은 다음의 값의 1 개에 세트 하지 않으면 .Em 되지 않습니다 . .Bl -tag -width indent .It Dv R_CURSOR 지정의 키에 관련지을 수 있었던 데이터가 돌려주어집니다. 이것은 커서를 키의 위치에 세트 또는 초기화한다고 하는 점으로 .Va get routine와 다릅니다 ( .Dv DB_BTREE 액세스 방식의 경우, 돌려주어진 키는 반드시 지정의 키와 정확하게 일치한다 필요가 없는 것에 주의해 주세요. 돌려주어지는 키는, 지정의 키보다 큰가 또는 동일한 것 같은, 최소의 키이며, 부분적인 키 일치와 범위 검색을 할 수 있습니다). .It Dv R_FIRST 데이타베이스의 최초의 키 / 데이터의 조가 돌려주어져 커서는 그것을 참조하도록(듯이) 세트 또는 초기화됩니다. .It Dv R_LAST 데이타베이스의 마지막 키 / 데이터의 조가 돌려주어져 커서는 그것을 참조하도록(듯이) 세트 또는 초기화됩니다 ( .Dv DB_BTREE (와)과 .Dv DB_RECNO 의 각 액세스 방식에만 적용할 수 있습니다). .It Dv R_NEXT 커서의 직후에 있는 키 / 데이터의 조를 꺼냅니다. 커서가 아직 세트되어 있지 않은 경우는, 이것은 .Dv R_FIRST 플래그와 같게 됩니다. .It Dv R_PREV 커서의 직전에 있는 키 / 데이터의 조를 꺼냅니다. 커서가 아직 설정되어 있지 않은 경우에는, 이것은 .Dv R_LAST 플래그와 같게 됩니다. ( .Dv DB_BTREE (와)과 .Dv DB_RECNO 의 각 액세스 방식에만 적용할 수 있습니다). .El .Pp .Dv R_LAST (와)과 .Dv R_PREV 하지만 이용할 수 있는 것은, .Dv DB_BTREE (와)과 .Dv DB_RECNO 의 각 액세스 방식에 관해서만입니다. 이것들은 각각 키에 변화하지 않는 고유의 순서가 있는 것을 의미하고 있기 때문입니다. .Pp .Va seq routine는 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려주어, 지정의 키 또는 현재의 키보다 작은가 또는 큰 키 / 데이터의 조가 존재하지 않는 경우는 1 을 돌려줍니다. .Dv DB_RECNO 액세스 방식이 사용되고 있어, 게다가 데이타베이스 파일이 캐릭터 특수 파일이며, 완전한 키 / 데이터의 조가 그 시점에서 존재하지 않는 경우, .Va seq routine는 2 를 돌려줍니다. .It Va sync 캐쉬된 정보를 디스크에 플래시 하는 routine를 가리키는 포인터. 데이타베이스가 메모리내에만 존재하는 경우, .Va sync routine에는 아무 효과도 없고, 처리는 항상 정상 종료합니다. .Pp .Fa flags 값은 다음의 값에 세트 할 수 있습니다. .Bl -tag -width indent .It Dv R_RECNOSYNC .Dv DB_RECNO 액세스 방식이 사용되는 경우, 이 플래그는 .Va sync routine가, .Va recno 파일 자신이 아니고, recno 파일의 기가 된다 btree 파일에 적용되도록(듯이) 합니다 (상세한 것에 대하여는 .Xr recno 3 메뉴얼 페이지의 .Va bfname 필드를 참조해 주세요). .El .Pp .Va sync routine는 에러 종료시에는 -1 을 반환 ( .Va errno (을)를 설정), 정상 종료시에는 0 을 돌려줍니다. .El .Sh 키 / 데이터의 조 모든 파일 타입에의 액세스는 키 / 데이터의 조를 기본으로 하고 있습니다. 키와 데이터의 양쪽 모두가 다음의 데이터 구조로 나타내집니다. .Bd -literal typedef struct { void *data; size_t size; } DBT; .Ed .Pp .Ft DBT 구조체의 요소는 다음과 같이 정의됩니다. .Bl -tag -width "data" .It Va data byte string를 가리키는 포인터. .It Va size byte string의 길이. .El .Pp 키와 데이터 byte string는, 동시에 이용할 수 있는 메모리에 피트할 필요 (은)는 있습니다만, 참조할 수 있는 캐릭터 라인의 길이에는 본질적으로는 제한이 없습니다. 액세스 방식은, byte string의 바이트 아라인에 대해서는 어떤 프로텍션도 하고 있지 않는 것에 주의해야 합니다. .Sh 에러 .Fn dbopen routine가 에러 종료하면(자), 프로그램 라이브러리 routine .Xr open 2 (이)나 .Xr malloc 3 그리고 쓰여져 있는 에러, 또는 아래와 같은 에러에 대한다 .Va errno (을)를 세트 합니다. .Bl -tag -width Er .It Bq Er EFTYPE 파일의 포맷이 잘못되어 있습니다. .It Bq Er EINVAL 기존의 파일 지정과 호환성이 없는 파라미터 (해쉬 함수, 패드 바이트등)이나, 함수에 의미가 없는 파라미터가 지정되었다 (예를 들어, 사전의 초기화가 행해지지 않은 커서의 사용), 또는 파일과 소프트웨어의 버젼간에 불일치가 있습니다. .El .Pp .Va close routine가 에러 종료하면(자), 프로그램 라이브러리 routine .Xr close 2 , .Xr read 2 , .Xr write 2 , .Xr free 3 , .Xr fsync 2 에 쓰여져 있는 에러에 대한 .Va errno (을)를 세트 합니다. .Pp .Va del , .Va get , .Va put , .Va seq 의 각 routine가 에러 종료하면(자), 프로그램 라이브러리 routine .Xr read 2 , .Xr write 2 , .Xr free 3 , .Xr malloc 3 에 쓰여져 있는 에러에 대한 .Va errno (을)를 세트 합니다. .Pp .Va fd routine는, 메모리내의 데이타베이스로 에러 종료하면(자), .Er ENOENT 에 .Va errno (을)를 세트 합니다. .Pp .Va sync routine가 에러 종료하면(자), 프로그램 라이브러리 routine .Xr fsync 2 에 쓰여져 있는 에러에 대한 .Va errno (을)를 세트 합니다. .Sh 관련 항목 .Xr btree 3 , .Xr hash 3 , .Xr mpool 3 , .Xr recno 3 .Rs . %T "LIBTP: Portable, Modular Transactions for UNIX" . %A Margo Seltzer . %A Michael Olson . %R "USENIX proceedings" . %D Winter 1992 .Re .Sh 버그 typedef .Ft DBTs (은)는, .Dq "data base thang" 의 약칭으로, 아직 사용되어 있지 않은 합리적인 이름을 아무도 생각해내지 못했기(위해)때문에 사용되게 되었습니다. .Pp 파일 기술자 인터페이스는 구성이 조화를 이루지 않고, 인터페이스의 향후의 버젼에서는 삭제될 예정입니다. .Pp 어느 액세스 방식도, 병행 액세스, 락, 또는 트랜잭션(transaction) (은)는, 어떠한 형식에서도 제공하지 않습니다.