.\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Casey Leedom of Lawrence Livermore National Laboratory. .\" .\" 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. .\" .\" @(#) getcap. 3 8.4 (Berkeley) 5/13/94 .\" .\" $FreeBSD: doc/ja_JP.eucJP/man/man3/getcap. 3, v 1.2 2001/05/14 01:08:35 horikawa Exp $ .Dd May 13, 1994 .Dt GETCAP 3 .Os .Sh 명칭 .Nm cgetent , .Nm cgetset , .Nm cgetmatch , .Nm cgetcap , .Nm cgetnum , .Nm cgetstr , .Nm cgetustr , .Nm cgetfirst , .Nm cgetnext , .Nm cgetclose .Nd 케이파비리티데이타베이스에 액세스 하는 routine .Sh 서식 .Fd #include .Ft int .Fn cgetent "char **buf" "char **db_array" "char *name" .Ft int .Fn cgetset "char *ent" .Ft int .Fn cgetmatch "char *buf" "char *name" .Ft char * .Fn cgetcap "char *buf" "char *cap" "int type" .Ft int .Fn cgetnum "char *buf" "char *cap" "long *num" .Ft int .Fn cgetstr "char *buf" "char *cap" "char **str" .Ft int .Fn cgetustr "char *buf" "char *cap" "char **str" .Ft int .Fn cgetfirst "char **buf" "char **db_array" .Ft int .Fn cgetnext "char **buf" "char **db_array" .Ft int .Fn cgetclose "void" .Sh 해설 .Fn cgetent (은)는, .Dv NULL 그리고 끝나는 파일 배열 .Fa db_array 그리고 지정한 데이타베이스로부터, 케이파비리티 .Em name (을)를 뽑아내, .Fa buf 안에 malloc 한 그 카피의 포인터를 돌려줍니다. .Fn cgetent 함수는 .Dv ASCII 파일에 액세스 하기 전에, 우선, .Nm .db 그리고 끝나는 파일을 찾습니다( .Xr cap_mkdb 1 참조). .Fa Buf (은)는, 이후의 .Fn cgetmatch , .Fn cgetcap , .Fn cgetnum , .Fn cgetstr 및 .Fn cgetustr 의 호출해 모두를 통해서 보관 유지되지 않으면 안됩니다만, 호출의 완료 후는 .Xr free 3 할 수 있습니다. 뽑아내에 성공했을 경우는 0이, 돌려주는 레코드에 미해결인 .Nm tc 확장이 포함되어 있는 경우는 1이, 요구된 레코드가 발견되지 않았던 경우는 \-1 하지만 돌아갑니다. 시스템 우류(파일을 오픈할 수 없었다/읽어내라 없었다, 등)이 발생했을 경우는 \-2 하지만 돌아가는 것과 동시에, .Va errno 하지만 설정됩니다. 또, 잠재적인 참조 루프가 검출되었을 경우는 \-3 하지만 돌아갑니다(후술의 .Ic tc= 참조). .Pp .Fn cgetset 함수는, 1 개의 케이파비리티레코드엔트리가 포함된, 캐라크타박 파의 케이파비리티데이타베이스에의 추가를 유효하게 합니다. 개념적으로는, 이 엔트리가 최초의 ``파일''로서 데이타베이스에 추가되므로, .Fn cgetent 의 호출에서는 최초로 검색됩니다. 엔트리는 .Fa ent 에게 건네집니다만, .Fa ent 하지만 .Dv NULL 의 경우, 현재의 엔트리는 데이타베이스로부터 제거됩니다. .Fn cgetset 의 호출은, 데이타베이스의 주사에 선행하지 않으면 안됩니다. .Fn cgetent 호출 전에, 호출할 필요가 있습니다. 시퀀셜인 액세스를 실행 하는 경우는, 최초의 시퀸셜 액세스 호출( .Fn cgetfirst 또는 .Fn cgetnext )의 전에 호출하는지, .Fn cgetclose 호출의 직후에 호출할 필요가 있습니다(후게참조). 호출에 성공했을 경우는 0 이, 실패했을 경우는 \-1 이 돌아갑니다. .Pp .Fn cgetmatch 함수는, .Em name 하지만 케이파비리티레코드 .Fa buf 의 이름의 하나라면 0을, 그렇지 않으면 \-1 (을)를 돌려줍니다. .Pp .Fn cgetcap 함수는, 타입 .Fa type 에 의해 케이파비리티 .Fa cap (을)를, 케이파비리티레코드 .Fa buf 그리고 검색합니다. 타입은, 1 개의 캐릭터를 사용해 지정합니다. 코론 (`:')(을)를 사용했을 경우는, 타입이 없는 케이파비리티가 검색됩니다(후게의 타입의 설명을 참조해 주세요). 검색이 성공했을 경우는 .Fa buf 에 있다 .Fa cap 값의 포인터가 돌아갑니다. 요구된 케이파비리티가 발견되지 않는 경우는, .Dv NULL 하지만 돌아갑니다. 케이파비리티치의 마지막은, .Ql : 또는 .Tn ASCII .Dv NUL 그리고 나타납니다(후게의 케이파비리티데이타베이스의 구문을, 참조해 관이야 있고). .Pp .Fn cgetnum 함수는, .Fa buf 그리고 나타난 케이파비리티레코드로부터, 수치 케이파비리티 .Fa cap 의 값을 꺼냅니다. 이 수치는 .Fa num 에 나타난다 .Ft long 그리고 돌려주어집니다. 성공했을 경우는 0이 돌아갑니다. 요구된 수치 케이파비리티가 발견되지 않는 경우는 \-1 이 돌아갑니다. .Pp .Fn cgetstr 함수는, .Fa buf 그리고 나타난 케이파비리티레코드로부터, 스트링케이파비리티 .Fa cap 의 값을 꺼냅니다. 그 string의 디코드되어 .Dv NUL 그리고 끝난다 .Xr malloc 된 카피의 포인터가, .Fa str 에 나타난다 .Ft char * 그리고 돌려주어집니다. 성공했을 경우는, 디코드된 string의 종단의 .Dv NUL (을)를 포함하지 않는 수가 돌아갑니다. 요구된 스트링케이파비리티가 발견되는거야 있고 경우는 \-1 이 돌아가, 시스템 우류(스토리지 할당 에러)가 발생해 경우는 \-2 이 돌아갑니다. .Pp .Fn cgetustr 함수는 .Fn cgetstr (와)과 같은 기능입니다만, 특수 캐릭터를 확장하지 않고, 오히려 케이파비리티 string의, 캐릭터 대로 각 캐릭터를 돌려주는 곳(중)이 다릅니다. .Pp .Fn cgetfirst 및 .Fn cgetnext 함수는, 파일명이 .Dv NULL 포인터로 끝나는 배열 .Fa db_array 에의, 시퀀셜인 액세스가 생기는 함수 그룹을 구성합니다. .Fn cgetfirst 함수는, 지정 데이타베이스에 있는 최초의 레코드를 돌려주어, 최초의 레코드에의 액세스를 리셋트 합니다. .Fn cgetnext 함수는, 전의 .Fn cgetfirst 또는 .Fn cgetnext 호출에 의해 돌아간 레코드의, 지정 데이타베이스에 있는 다음의 레코드를 돌려줍니다. 전의 호출이 없는 경우는, 지정 데이타베이스에 있는 최초의 레코 드를 돌려줍니다. 각 레코드는 .Fa buf 그리고 나타난다 .Xt malloc 된 카피로 돌아가, .Ic tc 확장이 이루어집니다. (후게의 .Ic tc= 의 설명을 참조해 주세요. ) 데이타베이스 검색을 완료해, 돌려주는 레코드가 없는 경우는 0이 돌아갑니다. 검색 에 성공해 돌려주는 레코드가 있어, 한층 더 다음의 레코드가 남아 있을 가능성이 (데이타베이스의 마지막에 아직 달하지 않았다) 경우는 1이 돌아갑니다. 돌려주는 레코 드에, 미해결인 .Nm tc 확장이 포함되어 있는 경우는 2가 돌아갑니다. 시스템 우류의 발생했을 경우는 \-1 하지만 돌아갑니다. 잠재적인 참조 루프가 검출되었을 경우는 \-2 이 돌아갑니다. (후게의 .Ic tc= 의 설명을 참조해 주세요. ) 데이타베이스가 완료했을(0이 돌아갈) 경우, 데이 타베이스는 클로우즈 됩니다. .Pp .Fn cgetclose 함수는, 시퀀셜인 액세스를 클로우즈 해, 모든 메모리 및 사용 되고 있던 파일 기술자를 해방합니다. .Fn cgetset 의 호출에 의해 푸쉬 된 버퍼는, 소거되지 않는 것에 주의해 주세요. .Sh 케이파비리티데이타베이스의 구문 케이파비리티데이타베이스는 일반적으로 .Tn ASCII 입니다. 표준의 텍스트 문자 편집기로 편집할 수 있습니다. 공백행 및 `#'로 시작된다 행은 코멘트이므로 무시됩니다. `\|\e'로 끝나는 행은, 다음의 행이 현재의 행 의 계속인 것을 나타냅니다. 이 `\|\e' 및 후에 계속되는 개행은 무시 . 긴 행은 보통 몇개의 물리행으로 분할되어 맨 마지막 줄을 제외해 각 행말에 `\|\e'가 붙일 수 있습니다. .Pp 케이파비리티데이타베이스는, 일련의 레코드(1 논리행 당 1개)에 의해 구성됩니다. 각 레코드에는, 가변수의 `:'로 나눌 수 있었던 필드(케이 파비리티)가 포함됩니다. 공백 스페이스 캐릭터(스페이스 및 탭)로, 모두 구성되는 필드는 무시됩니다. .Pp 각 레코드의 최초의 케이파비리티는, `|'캐릭터로 나눌 수 있었던 이름(복 수)를 지정합니다. 결정에 의해 마지막 이름은 항상 코멘트로, 룩크악 프타그로서의 의도는 없습니다. 예를 들어, .Nm termcap 데이타베이스의 .Em vt100 레코드의 처음은 다음과 같습니다. .Pp .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" .Pp 여기에서는 최초부터 4개의 이름이, 이 레코드의 액세스에 사용할 수 있습니다. .Pp 나머지의 공백이 아닌 케이파비리티는 각각, 옵션으로 타입 지정치가 후에 계속되는 이름을, (이름, 값) 결합 세트로 기술합니다. 다음과 같습니다. .Bl -column "nameTvalue" .It 이름 Ta "타입이 없는[불] 케이바비리티명 [진정한]" .It name Ns Em \&T Ns value Ta 치 .Em value (을)를 가지는 케이파비리티 .Pq Em name , \&T .It name@ Ta 존재하는 비케이파비리티 .Em name .It nameT@ Ta 존재하지 않는(비재의) 케이파비리티 .Pq Em name , \&T .El .Pp 이름은, 1개또는 복수의 캐릭터로 구성됩니다. 이름에는 `:'를 제외한다 모든 캐릭터를 포함할 수가 있습니다만, 인쇄 가능 캐릭터로 한정해 (이)라고, `#' ,`=' ,`%' ,`@'등의 그래픽 캐릭터의 사용을 피한다 의가, 통상은 최선입니다. 타입은, 케이파비리티명을 각각의 관련 타입 지정치로부터 구별하는데 사용되는 1개의 캐릭터입니다. `:'를 제외하는 모두 의 캐릭터를 사용할 수 있습니다만, 보통은 `#',`=' ,`%' , 등의 그라픽 쿠캐라크타가 사용됩니다. 값은 무제한한 수의 캐릭터로,`:'를 제쿠스 라고의 캐릭터를 사용할 수 있습니다. .Sh 케이파비리티데이타베이스의 의미론 케이파비리티레코드는, (이름, 값) 결합세트를 기술합니다. 이름은, 그것들에 결합된 복수의 값을 가질 수가 있습니다. 1개의 이름에 대한 이인 치는, 각각의 .Fa type 에 의해 식별됩니다. .Fn cgetcap 함수는, 케이파비리티명 및 그 값의 타입이 주어진, 이름의 값의 포 인터를 돌려줍니다. .Pp 타입 `#' 및 `='는 관용으로, 수치 및 string 타입 지정의 값을 시 합니다만, 이러한 타입의 그러한 용도 한정은 강제적인 물건이 아닙니다. 함수 .Fn cgetnum 및 .Fn cgetstr 에 의해,`#' 및 `='의 종래의 구문 및 의미론을 실행할 수 있습니다. 타이 프가 없는 케이파비리티는, 보통진치 및 위치를 각각 가리키는 존재 또는 비 재첨부의, 불 오브젝트를 나타냅니다. 이 해석은 간단하게 다음과 같이 겉(표) 일이 생깁니다. .Pp .Dl "(getcap(buf, name, ':') ! = NULL)" .Pp 특수 케이파비리티 .Ic tc= name (은)는, 이름에 의해 지정한 레코드를 .Ic tc 케이파비리티에 옮겨놓도록(듯이) 지시합니다. .Ic tc 케이파비리티는, 같은 .Ic tc 케이파비리티가 포함된 레코드를 보간 할 수 있습니다. 1개의 레코드내에서, 복수의 .Ic tc 케이파비리티를 사용할 수 있습니다. .Ic tc 의 확장 범위(즉 인수가 검색되는 범위)에는, .Ic tc 하지만 선언된 파일 이후의, 그 파일 배열에 있는 모든 파일이 함 . .Pp 케이파비리티레코드를 데이타베이스로 검색하는 경우는, 그 검색으로 최초로 적합한 레코드가 돌아갑니다. 케이파비리티를 레코드로 스캔 하는 경우는, 최초로 적합한 케이파비리티가 돌아갑니다. 케이파비리티 .Ic :nameT@: (은)는, 후에 계속되는 이름의 타입 .Em T 의 값의, 모든 정의를 숨깁니다. 또, 케이파비리티 .Ic :name@: (은)는, 후에 계속되는 이름의 모든 값을 불가시로 합니다. .Pp .Ic tc 케이파비리티와 짜 합쳐진 이러한 기능은, 새로운 케이파비리티를 추 가 하거나 새로운 정의에 의해 지금까지의 정의를 덧쓰기하거나 또는 `@' 케이파비리티에 의해 후에 계속되는 정의를 숨기거나 하는 것에 의해, 다른 데이 타베이스 또는 레코드를 여러가지로 변화시킬 수가 있습니다. .Sh 예 .Bd -unfilled -offset indent example\||\|an example of binding multiple values to names:\e :foo%bar:foo^blah:foo@:\e :abc%xyz:abc^frap:abc$@:\e :tc=more: .Ed .Pp 케이파비리티 foo 에는 거기에 결합된 2 개의 값(타입 `%'의 bar 및 타입 `^'의 blah)가 있습니다. 결합된 것 외의 모든 값은 숨겨져 있습니다. 케이파비리티 abc 에도 결합된 2개의 값이 있습니다만, 케이파비리티레코드 more 에서의 정의가 금지되고 있는 것은, 타입 `$'의 값 뿐입니다. .Pp .Bd -unfilled -offset indent file1: new\||\|new_record\||\|a modification of "old":\e :fript=bar:who-cares@:tc=old:blah:tc=extensions: file2: old\||\|old_record\||\|an old database record:\e :fript=foo:who-cares:glork#200: .Ed .Pp 이러한 레코드를 뽑아내는 경우는, file2의 전에 file1로 .Fn cgetent (을)를 호출합니다. 거기에 따라 file1 의 신케이파비리티레코드 fript=bar 가, file2 의 구케이파비리티레코드로부터 보간 된 fript=foo (을)를 덧쓰기합니다. 또, who-cares@ 가 구레코드에 있는 모든 who-cares 정의를 불가시로 합니다. 게다가 glork#200 가 구레코드로부터 미루어져 blah 및, 이 레코드의 확장에 의해 정의된 모두가 구레코드내의 그것들 정의에 추가됩니다. 여기에서는, tc=old 의 전에 fript=bar 및 who-cares@ 의 정의를 두는 것이 중요합니다. 그러한 정의를 tc=old 의 뒤에 치 있었을 경우는, 구레코드의 정의가 우선됩니다. .Sh CGETNUM 및 CGETSTR의 구문과 의미론 .Fn cgetnum 및 .Fn cgetstr 에 의해 정의완료의, 2개의 타입이 있습니다. 다음과 같습니다. .Bl -column "nameXnumber" .Sm off .It Em name No \&# Em number Ta "치" .Em number (을)를 가지는 수치 케이파비리티명 .It Em name No = Em string Ta "치" .Em string (을)를 가지는 스트링케이파비리티명 .It Em name No \&#@ Ta "존재하지 않는(비 재) 수치 케이파비리티명" .It Em name No \&=@ Ta "존재하지 않는(비 재) 스트링케이파비리티명" .El .Pp 수치 케이파비리티치는, 3 개의 기수의 어떤 것인가로 줄 수가 있습니다. . Q1 0x 또는 . Q1 0X 그리고 시작되는 수는, 16 진수로서 해석됩니다(대문자 및 소문자의 a-f 를 사 (이)라고 16 진수의 확장자리수를 나타낼 수가 있습니다). 그 외의 . Q1 0 그리고 시작된다 숫자는, 8 진수로서 해석됩니다. 나머지의 숫자는 모두 10 진수로서 해석 됩니다. .Pp 스트링케이파비리티치에는, 모든 캐릭터를 포함할 수가 있습니다. 인쇄 가능하지 않다 .Dv ASCII 코드, 개행 코드나 코론등이, escape sequence를 사용해 간단하게 겉(표) . 다음과 같습니다. .Bl -column "\e\|X, X\e\|X" "(ASCII octal nnn)" ^X ('X' & 037) 컨트롤 X \e\|b, \e\|B (ASCII 010) 백 스페이스 \e\|t, \e\|T (ASCII 011) 탭 \e\|n, \e\|N (ASCII 012) 라인 피드(개행) \e\|f, \e\|F (ASCII 014) form feed \e\|r, \e\|R (ASCII 015) 왕복대 리턴 \e\|e, \e\|E (ASCII 027) 이스케이프 \e\|c, \e\|C (:) 코론 \e\|\e (\e\|) backslash \e\|^ (^) caret \e\|nnn (ASCII 8 진수 nnn) .El .Pp `\|\e 의 뒤에 최대 3 자리수의 8 진수를 계속하면, 특정 캐릭터의 수치 코드를 직접 지정할 수가 있습니다. 다만, encode는 간단해도 .Dv ASCII .Dv NUL (을)를 다용하면(자), 모든 문제의 원인이 될 가능성이 있습니다. .Dv NUL (은)는 보통 string의 마지막을 나타내기 때문에, 사용에 있어서는 주의가 필요 입니다. 많은 어플리케이션으로, .Dv NUL (을)를 나타내는데 `\e\|200'가 사용되고 있습니다. .Sh 진단 .Fn Cgetent , .Fn cgetset , .Fn cgetmatch , .Fn cgetnum , .Fn cgetstr , .Fn cgetustr , .Fn cgetfirst , 및 .Fn cgetnext 등은, 모두 성공했을 경우는 0또는 그것을 웃도는 값을 돌려주어, 실패한 장소 합은 0을 밑도는 값을 돌려줍니다. .Fn cgetcap 함수의 경우는, 성공하면(자) 캐릭터 포인터를, 실패하면(자) .Dv NULL (을)를 돌려줍니다. .Pp .Fn cgetent 및 .Fn cgetseq 함수의 실패에서는, .Va errno 하지만, 다른 프로그램 라이브러리 함수 .Xr fopen 2 , .Xr close 2 , .Xr open 2 , 및 .Xr close 2 등의 에러로 설정되는 경우가 있습니다. .Pp .Fn cgetent , .Fn cgetset , .Fn cgetstr 및 .Fn cgetustr 의 실패에서는, 다음의 에러에 .Va errno 하지만 설정되는 경우가 있습니다. .Bl -tag -width Er .It Bq Er ENOMEM 할당하는 메모리가 없습니다. .El .Sh 관련 항목 .Pp .Xr cap_mkdb 1 , .Xr malloc 3 .Sh 버그 코론 (`:')이, 이름, 타입, 값에 사용할 수 없습니다. .Pp .Fn cgetent 에, .Ic tc=name 루프의 체크가 없습니다. .Pp .Fn cgetset 의 호출에 의해 버퍼를 데이타베이스에 추가하는 것은, 이 데이타베이 스에 한정하지 않습니다만, 다른 사용 데이타베이스에 추가하는 경우는, 다음에는 없고 전 에 부가하는 (분)편이 무난합니다.