FTS(3)

명칭
fts - 파일의 계층을 횡단한다

프로그램 라이브러리
libc

서식
<sys/types.h> <sys/stat.h> <fts.h> FTS * fts_open(char * const *path_argv, int options, int (*compar)(const FTSENT **, const FTSENT **)) FTSENT * fts_read(FTS *ftsp) FTSENT * fts_children(FTS *ftsp, int options) int fts_set(FTS *ftsp, FTSENT *f, int options) int fts_close(FTS *ftsp)

해설
fts (은)는, UNIX 파일 계층을 횡단하기 위한 함수입니다. 간단하게 설명하면(자), fts_open() 함수는 파일 계층의 “핸들” (을)를 되돌립니다. 이 핸들은, 그 외의 fts 함수로 지정할 수 있습니다. fts_read() 함수는, 파일 계층의 1 개의 파일을 나타내는 구조체의 포인터를 되돌립니다. fts_children() 함수는, 구조체의 링크 리스트에의 포인터를 되돌립니다. 각 구조체는, 그 계층이 있는 디렉토리에 포함되는 파일 1 개(살)을 나타냅니다. 일반적으로, 디렉토리는, 정순 (어느 아이에게 액세스 하기 전)과 역순 (모든 아이에게 액세스 한 후 )의 2 회 액세스 됩니다. 파일은 1 회 액세스 됩니다. 기호 연결을 무시한, 계층에의 “논리적인” 액세스, 기호 연결을 더듬는, 계층에의 물리적인 액세스, 계층에의 액세스 인스트럭션, 계층의 일부의 분리나 재액세스가 가능합니다.

인클루드 파일 <fts.h> 에는, 2 개의 구조체가 정의되고 (한편, typedef 형 정의도 되고) 있습니다. 1 개(살)은, 파일 계층 그 자체를 나타내는 구조체 FTS 입니다. 이제(벌써) 1 개(살)은, 파일 계층의 파일 1 개(살)을 나타내는 구조체 FTSENT 입니다. 통상은, 파일 계층의 파일 모두에 임해서, 구조체 FTSENT 하지만 1 개(살) 되돌려집니다. 이 메뉴얼 페이지에서는, “파일” (와)과 “FTSENT 구조체” (은)는, 거의 같은 의미를 가집니다. FTSENT 구조체에는, 적어도 이하에 나타내는 필드를 포함합니다. 각각의 필드에 대해서는, 다음에 자세하게 설명합니다.

    typedef struct _ftsent {
    	u_short fts_info;		/* flags for FTSENT structure */
    	char *fts_accpath;		/* access path */
    	char *fts_path;			/* root path */
    	u_short fts_pathlen;		/* strlen(fts_path) */
    	char *fts_name;			/* file name */
    	u_short fts_namelen;		/* strlen(fts_name) */
    	short fts_level;		/* depth (-1 to N) */
    	int fts_errno;			/* file errno */
    	long fts_number;		/* local numeric value */
    	void *fts_pointer;		/* local address value */
    	struct ftsent *fts_parent;	/* parent directory */
    	struct ftsent *fts_link;	/* next file structure */
    	struct ftsent *fts_cycle;	/* cycle structure */
    	struct stat *fts_statp;		/* stat(2) information */
    } FTSENT;

이러한 필드는, 이하와 같이 정의되고 있습니다.

fts_info
    되돌려졌다 FTSENT 구조체와 그것이 나타내는 파일을 기술합니다. 이하중 1 개의 값을 받습니다. 에러가 없는 디렉토리 (FTS_D) (을)를 제외하면, 모든 엔트리는 종단입니다. 즉, 재액세스 되는 것은 없고, 아이가 액세스 되는 일도 없습니다.

    FTS_D
        정순으로 액세스 되는 디렉토리입니다.

    FTS_DC
        트리에서의 순환의 원인이 되는 디렉토리입니다. ( FTSENT 구조체의 fts_cycle 필드에도와 같이 이 정보가 들어갑니다. )

    FTS_DEFAULT
        다른 어느 fts_info 의 값으로도 명확하게 나타내지 않는 파일 타입을 나타낸다 FTSENT 구조체입니다.

    FTS_DNR
        읽어들일 수 없는 디렉토리입니다. 이것은 에러 리턴으로, fts_errno 필드에 에러의 원인을 나타내는 값이 설정됩니다.

    FTS_DOT
        fts_open() 에 파일명으로서 지정되어 있지 않은, ‘.’ (이)나, ‘..’ (이)라는 이름을 가지는 파일입니다 ( FTS_SEEDOT (을)를 참조).

    FTS_DP
        역순으로 액세스 되는 디렉토리입니다. 정순 (즉, fts_info 필드에 FTS_D 하지만 설정되었을 경우)로 돌아왔을 때는, FTSENT 구조체의 내용은 변경되고 있지 않습니다.

    FTS_ERR
        이것은 에러 리턴이며, fts_errno 필드에 에러의 원인이 설정됩니다.

    FTS_F
        통상 파일입니다.

    FTS_NS
        stat(2) 그리고 정보를 취득할 수 없는 파일입니다. fts_statp 필드의 내용은 미정도리가 됩니다. 이것은 에러 리턴이며, fts_errno 필드에 에러의 원인을 나타내는 값이 설정됩니다.

    FTS_NSOK
        stat(2) 에서의 정보 취득을 요구하지 않는 파일입니다. fts_statp 필드의 내용은 부정이 됩니다.

    FTS_SL
        기호 연결입니다.

    FTS_SLNONE
        타겟이 존재하지 않는 기호 연결입니다. fts_statp 필드의 내용은, 그 기호 연결 자체의 파일 특성 정보를 참조합니다.

fts_accpath
    커런트 디렉토리로부터 파일에 액세스하기 위한 패스입니다.

fts_path
    횡단의 루트로부터의, 파일의 상대 패스입니다. 이 패스에는, fts_open() (으)로 지정한 패스가 접두어로서 포함됩니다.

fts_pathlen
    fts_path 하지만 참조하는 캐릭터 라인의 길이입니다.

fts_name
    파일의 이름입니다.

fts_namelen
    fts_name 하지만 참조하는 캐릭터 라인의 길이입니다.

fts_level
    이 파일이 발견된 장소의, 이 횡단에 있어서의 깊이입니다. 이 깊이는 -1 (으)로부터 N 까지의 번호를 붙일 수 있습니다. 횡단의 개시점의 부모 (또는 루트)를 나타낸다 FTSENT 구조체에는, 번호 FTS_ROOTPARENTLEVEL (-1)(이)가 첨부 됩니다. 루트의 FTSENT 구조체에는, 번호 FTS_ROOTLEVEL (0)(이)가 첨부 됩니다.

fts_errno
    함수 fts_children() 혹은 fts_read() 하지만 구조체 FTSENT (을)를 되돌림에 즈음해, fts_info 필드에 FTS_DNR, FTS_ERR, FTS_NS 중 한쪽이 설정된 상태의 경우는, fts_errno 필드는, 에러의 원인을 나타내는 외부 변수 errno 의 값을 포함합니다. 그 외의 경우, fts_errno 필드의 내용은 미정도리입니다.

fts_number
    이 필드는, 응용 프로그램으로 사용하기 위한의 것으로, fts 함수군은 이 필드를 변경하지 않습니다. 이 필드는 0 으로 초기화되고 있습니다.

fts_pointer
    이 필드는, 응용 프로그램으로 사용하기 위한의 것으로, fts 함수군은 이 필드를 수정하지 않습니다. 이 필드는 NULL 그리고 초기화되고 있습니다.

fts_parent
    이 파일이 멤버가 되고 있는 디렉토리와 같이, 현재 주목하고 있다 파일의 바로 위의 계층에 있는 파일을 참조한다 FTSENT 구조체의 포인터입니다. 초기 엔트리 포인트의 친구조체도 제공됩니다만, fts_level 필드, fts_number 필드, fts_pointer 필드의 초기화 밖에 프로텍션되지 않습니다.

fts_link
    fts_children() 함수로부터 돌아오면(자), fts_link 필드는, 디렉토리의 멤버를 나타내는, 널 종단 된 링크 리스트 안의다음의 구조체를 가리킵니다. 그 외의 경우, fts_link 필드의 내용은 미정도리입니다.

fts_cycle
    디렉토리 2 개의 사이의 하드 링크나, 디렉토리를 가리킨다 기호 연결에 의해, 어느 디렉토리가 계층 구조 중(안)에서 순환의 원인이 되고 있는 경우 ( FTS_DC 참조), 이 구조체의 fts_cycle 필드는, 이 계층 구조 중(안)에서, 현재의 FTSENT 구조체와 같은 파일을 참조한다 FTSENT 구조체를 가리킵니다. 그 외의 경우, fts_cycle 필드의 내용은 미정도리입니다.

fts_statp
    파일의 stat(2) 의 정보를 가리키는 포인터입니다.

파일 계층에 있는 전파일의 모든 패스에 대해, 1 개의 버퍼를 사용합니다. 이 때문에, fts_path 필드와 fts_accpath 필드는, NUL종단 되고 있다 일이 프로텍션되는 것은, fts_read() 하지만 마지막에 되돌린 파일 마셔 입니다. 다른 FTSENT 구조체가 나타내는 파일을 참조하기 위해서, 이 필드를 사용하기 위해서는, 그 FTSENT 구조체의 fts_pathlen 필드에 포함되는 정보로 패스 버퍼를 수정할 필요가 있습니다. fts_read() (을)를 한층 더 호출하기 전에, 이러한 수정을 바탕으로 되돌려 둘 필요가 있습니다. fts_name 필드는, 항상 NUL종단 되고 있습니다.

FTS_OPEN
함수 fts_open() (은)는, 횡단 대상의 논리 파일 계층을 구성한다 1 개(살) 이상의 패스를 지정하는 캐릭터형 포인터의 배열을 가리키는 포인터를 취합니다. 배열은, NULL 포인터로 끝나 있을 필요가 있습니다.

수많은 옵션이 있습니다만, 최악이어도 다음중 1 개(살) ( FTS_LOGICAL 인가 FTS_PHYSICAL) (을)를 지정할 필요가 있습니다. 옵션은, 이하의 값의 논리합을 취하는 것으로 선택됩니다.

FTS_COMFOLLOW
    이 옵션을 지정하면(자), FTS_LOGICAL 하지만 지정되어 있는지 어떤지에 관련되지 않고, 루트 패스로 해서 지정되었다 기호 연결이 곧바로 더듬어집니다.

FTS_LOGICAL
    이 옵션을 지정하면(자), fts routine는, 기호 연결 그 자체가 아니고, 기호 연결의 타겟의 FTSENT 구조체를 되돌리게 됩니다. 이 옵션을 설정하면(자), 어플리케이션에 되돌려진다 FTSENT 구조체가 가리키는 기호 연결은, 존재하지 않는 파일을 참조하는 것만으로 됩니다. fts_open() 함수에는, FTS_LOGICAL 인가 FTS_PHYSICAL (을)를 지정할 필요가 있습니다.

FTS_NOCHDIR
    퍼포먼스를 최적화하기 위해(때문에), fts 함수는, 파일 계층의 액세스중에 커런트 디렉토리를 변경합니다. 이것에는, 횡단중에 어느 디렉토리 에 있을지가 어플리케이션으로 특정할 수 없다고 하는 부작용이 있습니다. FTS_NOCHDIR 옵션은 이 최적화를 무효로 하므로, fts 함수는 커런트 디렉토리를 변경하지 않게 됩니다. FTS_NOCHDIR (을)를 지정하고 있지 않는, 혹은, fts_open() 에 절대 패스명을 인수로서 지정하고 있지 않는 경우는, 어플리케이션으로 커런트 디렉토리를 변경하거나 파일에 액세스 하거나 하지 말아 주세요.

FTS_NOSTAT
    디폴트에서는, 되돌려진다 FTSENT 구조체는, 액세스 한 파일 각각 붙어 파일 특성 정보 ( statp 필드)를 참조하고 있습니다. 이 옵션은, 퍼포먼스를 최적화하기 위해서 이 요건을 완화해, fts 함수가 fts_info 필드에 FTS_NSOK (을)를 설정해, statp 필드의 내용을 미정도리대로 하는 것을 허가합니다.

FTS_PHYSICAL
    이 옵션을 지정하면(자), fts routine는, 기호 연결이 가리키는 타겟 파일이 아니고, 기호 연결 자체의 FTSENT 구조체를 되돌리게 됩니다. 이 옵션을 설정하면(자), 계층에 존재하는 모든 기호 연결의 FTSENT 구조체가 어플리케이션에 되돌려집니다. fts_open() 함수에는, FTS_LOGICAL 인가 FTS_PHYSICAL (을)를 지정할 필요가 있습니다.

FTS_SEEDOT
    디폴트에서는, fts_open() 의 패스 인수로서 지정하지 않는 한, 파일 계층에 존재하는, ‘.’ 혹은, ‘..’ (이)라는 이름의 파일은 무시됩니다. 이 옵션을 지정하는 것으로써, fts routine는, 이러한 파일의 FTSENT 구조체를 되돌리게 됩니다.

FTS_XDEV
    이 옵션을 지정하면(자), fts (은)는, 하강을 시작한 파일과 다른 디바이스 번호를 가지는 디렉토리에 하강하지 않습니다.

인수 compar() (은)는, 계층 횡단의 순서 규칙에 사용되는 유저 정의 함수를 지정합니다. 이 함수는, FTSENT 구조체의 포인터를 가리키는 2 개의 포인터를 인수로서 취해, 최초의 인수가 참조하는 파일이, 2 번째의 인수가 참조하는 파일보다 앞에 오는지, 전에서도 뒤에서도 어디라도 상관없는지, 뒤로 올까에 의해, 각각 부의 값, 0, 정의 값을 되돌리지 않으면 되지 않습니다. 이 비교에서는, FTSENT 구조체의 fts_accpath, fts_path, fts_pathlen 필드를 절대로 사용 해서는 안됩니다. fts_info 필드에 FTS_NS 인가 FTS_NSOK 하지만 설정되어 있는 경우, fts_statp 필드도 사용해 되지 않습니다. 인수 compar() 하지만 NULL 인 경우, 디렉토리 횡단 순서는, 루트 패스로는 path_argv 그리고 리스트 되는 순서에, 그 외 모든 장소에서는, 디렉토리에서 리스트 되고 있는 순서가 됩니다.

FTS_READ
fts_read() 함수는, 계층의 파일을 나타낸다 FTSENT 구조체의 포인터를 되돌립니다. 디렉토리 (독 붐비어 가능해 순환의 원인이 되지 않는 걸)(은)는, 정순탐색시에 1 회와 역순탐색시에 1 회, 적어도 2 회 액세스 됩니다. 그 외 모든 파일은, 최저 1 회 액세스 됩니다. (디렉토리간의 하드 링크로 순환의 원인이 되지 않는 것, 또는 기호 연결에 대한 기호 연결은, 파일의 경우, 1 회 이상 액세스 되는 원인이 되어, 디렉토리의 경우, 2 회 이상 액세스 되거나 하는 원인이 되는 일이 있습니다. )

계층의 모든 멤버가 되돌려지면(자), fts_read() 하 NULL (을)를 되돌려, 외부 변수 errno 에 0 을 설정합니다. 계층안의 파일과 무관계한 에러가 발생하면(자), fts_read() 하 NULL (을)를 되돌려, errno 에 적절한 값을 설정합니다. 되돌려지는 파일에 관계하는 에러가 발생하면(자), FTSENT 구조체의 포인터가 되돌려져 errno (은)는 설정되거나 설정되지 않거나 합니다 ( fts_info 참조).

fts_read() 하지만 되돌린다 FTSENT 구조체는, 같은 파일 계층 스트림에 대해서 fts_close() (을)를 호출한 후, 혹은, 그 구조체가 디렉토리형 파일을 나타내지 않은 경우에 같은 파일 계층 스트림에 대해서 fts_read() (을)를 호출한 후, 덧쓰기되는 일이 있습니다. 어느 쪽의 경우에서도, 역순탐색 시에 fts_read() 하지만 FTSENT (을)를 돌려준 후에 fts_read() (을)를 호출할 때까지는, FTSENT 구조체는 덧쓰기되지 않습니다.

FTS_CHILDREN
함수 fts_children() (은)는, fts_read() 하지만 최근 되돌렸다 FTSENT 구조체가 나타낸다 디렉토리의 파일의 NULL 로 끝나는 링크 리스트의 최초의 엔트리이다 FTSENT 구조체의 포인터를 되돌립니다. 리스트는, FTSENT 구조체의 fts_link 필드에서 링크 되어 유저 정의 비교 함수가 있는 경우는, 그래서 순서 붙일 수 있습니다. fts_children() (을)를 반복해 호출하면(자), 이 링크 리스트는 그때마다 재작성됩니다.

특별한 경우로서 그 계층에서 fts_read() 하지만 아직 불려 가지 않은 경우, fts_children() (은)는, fts_open() (으)로 지정되었다 논리 디렉토리에 있는 파일 (즉, ftp_open() (으)로 지정된 인수)를 가리키는 포인터를 되돌립니다. fts_read() 하지만 벌써 불려 가고 있을 때, fts_read() 하지만 최근 되돌렸다 FTSENT 구조체가, 정순탐색으로 액세스 된 디렉토리가 아닌지, 디렉토리에 파일이 포함되지 않은 경우, fts_children() 하 NULL (을)를 되돌려, errno 에 0 을 설정합니다. 에러가 발생하면(자), fts_children() 하 NULL (을)를 되돌려, errno 에 적절한 값을 설정합니다.

fts_children() 하지만 되돌린다 FTSENT 구조체는, 같은 파일 계층 스트림을 사용했다 fts_children(), fts_close(), fts_read() 의 호출의 뒤, 덧쓰기되는 일이 있습니다.

option 에는, 이하의 값을 설정할 수 있습니다.

FTS_NAMEONLY
    파일의 이름만이 필요한 것을 나타냅니다. 되돌려진 구조체의 링크 리스트에 존재하는 모든 필드의 내용은, fts_name 필드와 fts_namelen 필드를 제외해 미정도리가 됩니다.

FTS_SET
함수 fts_set() 에 의해, 스트림 ftsp 의 파일 f 에 대해서, 한층 더 행하는 처리를 유저 어플리케이션이 결정할 수가 있습니다. fts_set() 함수는, 문제가 없으면 0 을 되돌려, 에러가 발생했을 경우는 -1 을 되돌립니다. option (으)로서 이하 중 1 개의 값을 설정할 필요가 있습니다.

FTS_AGAIN
    파일을 재액세스 합니다. 어떠한 파일 타입의 파일도 재액세스 될 가능성이 있습니다. 그 다음에 fts_read() (을)를 호출하는 것으로, 참조된 파일이 되돌려집니다. 그 때, 구조체의 fts_stat 필드와 fts_info 필드가 다시 초기화됩니다만, 그 외의 필드는 변경되지 않습니다. 이 옵션은, fts_read() 하지만 최근 되돌린 파일 에 대해서만 의미를 가집니다. 통상의 경우는 역순 디렉토리 액세스에 사용합니다. 이 경우는 디렉토리가 정순과 역순의 양쪽 모두로 재액세스 되어 그 아이 모두도 재액세스 됩니다.

FTS_FOLLOW
    참조하는 파일은, 기호 연결일 필요가 있습니다. 참조하는 파일이, fts_read() 그리고 최근 되돌려진 것인 경우, 다음에 fts_read() (을)를 호출하면(자), fts_info 필드와 fts_statp 필드가 초기화되어 기호 연결 자체는 아니고 기호 연결의 타겟을 가리킨 상태로 파일이 되돌려집니다. 파일이 fts_children() 그리고 최근 되돌려진 것인 경우, 구조체의 fts_info 필드와 fts_statp 필드는, fts_read() 그리고 되돌려지면(자), 기호 연결 자체는 아니고 기호 연결의 타겟을 반영합니다. 어느 쪽의 경우에서도, 기호 연결의 타겟이 존재하지 않으면, 되돌려지는 구조체의 필드 (은)는 변경되지 않고, fts_info 필드는 FTS_SLNONE (으)로 설정됩니다.

    링크의 타겟이 디렉토리인 경우는, 정순탐색에서의 리턴, 모든 자손의 리턴, 역순탐색의 리턴이 이 순서로 실행됩니다.

FTS_SKIP
    이 파일의 아이는 액세스 되지 않습니다. 여기서 지정하는 파일로서 fts_children() 인가 fts_read() 하지만 최근 되돌린 것 어느 쪽인지가 가능합니다.

FTS_CLOSE
함수 fts_close() (은)는, 파일 계층 스트림 ftsp (을)를 닫아 커런트 디렉토리를, fts_open() (을)를 호출했을 때의 디렉토리에 되돌립니다. fts_close() 함수는, 에러가 없으면 0 을 되돌려, 에러가 발생했을 경우는 -1 을 되돌립니다.

에러
fts_open() 함수의 실행이 실패해 에러가 되면(자), 프로그램 라이브러리 함수 open(2) (와)과 malloc(3) 그리고 지정된 에러가 errno (으)로 설정되는 일이 있습니다.

fts_close() 함수가 에러가 되면(자), 프로그램 라이브러리 함수 chdir(2) (와)과 close(2) 하지만 지정한 에러가 errno 설정되는 일이 있습니다.

fts_read() 함수와 fts_children() 함수가 에러가 되면(자), 프로그램 라이브러리 함수 chdir(2), malloc(3), opendir(3), readdir(3), stat(2) 그리고 지정된 에러가 errno (으)로 설정되는 일이 있습니다.

fts_children(), fts_open(), fts_set() 하지만 에러가 되면(자), 이하와 같이 errno (을)를 설정합니다.

[EINVAL]
    옵션이 올바르지는 않습니다.

관련 항목
find(1), chdir(2), stat(2), qsort(3)

표준
fts 유틸리티는, 장래, p1003.1-88 리버젼에 짜넣어진다고 생각됩니다.