LIBSTAND(3)

명칭
libstand - standalone 실행용 서포트 프로그램 라이브러리

서식
<stand.h>

해설
libstand (은)는, standalone 어플리케이션의 서포트 함수군과 표준 BSD 프로그래밍이 가능한 모의 환경을 갖추고 있습니다. 후의 섹션으로 이러한 함수를 종류구분 하고 있습니다. 여기에 명확한 정의가 없는 경우는, 지정의 함수의 섹션 3 의 메뉴얼 페이지의 해당 개소를 참조해 주세요.

캐릭터 라인 함수
사용할 수 있는 캐릭터 라인 함수는, string(3) 및 bstring(3) 에 쓰여져 있습니다.

메모리 얼로케이션

    void * malloc(size_t size)

    size 그리고 지정한 크기의 메모리를 최적인 알고리즘으로 heap area로부터 나누어 맞힙니다.

    void free(void *ptr)

    ptr 에 할당할 수 있었던 오브젝트를 해방합니다.

    void setheap(void *start, void *limit)

    heap area를 초기화합니다. 이 함수는, alloc() (을)를 최초로 호출하기 전에 실행하지 않으면 안됩니다. start (와)과 limit 의 사이의 area가 heap area에 사용됩니다. 이것을 넘어 할당하려고 하면(자) panic 가 됩니다.

    char * sbrk(int junk)

    sbrk(0) 의 성질을 줍니다. 즉 heap area의 최고정도 주소의 포인터를 돌려줍니다. 이 반환값은, 테스트시에 heap의 실 사용 상황을 판단하는데 사용할 수 있습니다. 인수 junk (은)는 무시됩니다.

환경
전통적인 쉘 서포트 환경에 같이, 플랫인 변수 공간 조작을 위해서(때문에) 한 무리의 함수가 갖춰지고 있습니다. 주된 확장으로서 훅 함수의 설정/설정 해제의 유익의 서포트가 있습니다.

    char * getenv(const char *name)

    int setenv(const char *name, char *value, int overwrite)

    int putenv(const char *string)

    int unsetenv(const char *name)

    이러한 함수는, 표준 프로그램 라이브러리와 유사한 동작을 합니다.

    struct env_var * env_getenv(const char *name)

    그 환경내에서의 변수를 검색해, 모든 데이터 구조를 돌려줍니다.

    int env_setenv(const char *name, int flags, char *value, ev_sethook_t sethook, ev_unsethook_t unsethook)

    name 그렇다고 하는 환경 변수의 신규 작성 또는 기존 환경 변수의 설정을 실시합니다. 신규 변수를 생성하는 경우는, 인수 sethook 및 unsethook (을)를 지정할 수가 있습니다.

    EV_NOHOOK 플래그가 설정되어 있지 않으면, 변수 설정을 하려고 한다고 하면(자), 훅의 설정이 반드시 기동됩니다. 통상, 인수 value 의 확인을 행해, 실제로 값을 보존하기 위해서 EV_NOHOOK 변수를 붙여, 재차 env_setenv() 호출을 실시해 설정합니다. 모든 변수 설정을 거부하기 위해서, 정의가 끝난 함수 env_noset() (을)를 지정할 수가 있습니다.

    설정 해제 훅은, 변수의 설정 해제를 할 때 기동됩니다. 반환값이 0 때, 변수의 설정 해제되고 있습니다. 정의가 끝난 함수 env_nounset (은)는, 변수 설정 해제를 억제하는데 사용합니다.

표준 프로그램 라이브러리 서포트

    int getopt(int argc, char * const *argv, cont char *optstring)

    long strtol(const char *nptr, char **endptr, int base)

    void srandom(unsigned long seed)

    unsigned long random(void)

    char * strerror(int error)

    libstand 그리고 서포트되고 있는 errno 의 부분집합치에 대응한다 에러 메세지를 돌려줍니다.

assert(expression)

    <assert.h> 행이 필요합니다.

    int setjmp(jmp_buf env)

    void longjmp(jmp_buf env, int val)

    조작할 수 있는 시그널 상태가 없기 때문에, 각각 _setjmp() 및 _lonjmp() (으)로서 정의되고 있습니다. <setjmp.h> 행이 필요합니다.

캐릭터 I/O

    void gets(char *buf)

    캐릭터를 콘솔로부터 buf 에 읽어들입니다. 표준적인 주의 사항이 본함수에 대해 적용됩니다.

    void ngets(char *buf, size_t size)

    size -1 또는 그것 이하의 캐릭터를 콘솔로부터 buf 에 읽어들입니다. 줄 끝 캐릭터는 삭제되어 버퍼는 항상 눌이 종단 캐릭터가 됩니다. size 하지만 1 이하의 경우, 함수는 gets() (와)과 같은 동작을 합니다.

    int fgetstr(char *buf, int size, int fd)

    일행을 size 캐릭터 이하의 범위에서 buf 에 읽어들입니다. 줄 끝의 캐릭터는 잘라 버릴 수 있어 버퍼는 항상 눌이 종단이 됩니다. 정상 종료 때는 buf 안의 캐릭터수를 돌려주어, read error 때는 -1 을 돌려줍니다.

    int printf(const char *fmt, ...)

    void vprintf(const char *fmt, va_list ap)

    int sprintf(char *buf, const char *fmt, ...)

    void vsprintf(char *buf, const char *fmt, va_list ap)

    *printf 함수는, 표준 printf() 패밀리의 부분집합 기능 물어 구두인가의 확장 기능을 갖추고 있습니다. c, d, n, o, p, s, u, x 의 표준 변환이 서포트되고 있습니다. +,-,#,*, 0, field width, precision, l 의 수식자가 서포트되고 있습니다.

    에러 레지스터를 디코드하기 위해서 b 변환이 갖춰지고 있습니다. 사용법은 이하와 같습니다.

    printf( "reg=%b\n", regval, "<base><arg>*" );

    <base> (은)는, 제어 캐릭터의 출력을 표현하고 있습니다. 예를 들면 \10 는 10 진수를, \20 는 16 진수를 의미합니다. 각 <arg> (은)는, 캐릭터 라인으로, 최초의 한 글자는 인수의 비트수(초가 1)로, 비트가 설정되어 있는 경우, 그 이후의 캐릭터 라인(32 캐릭터 미만)은 표시 대상의 텍스트입니다. 즉,

    printf( "reg=%b\n" 3 "\10\2BITTWO\1BITONE\n" );

    에 의해 출력 표시됩니다.

    reg=3<BITTWO,BITONE>

    D 변환은, 16 진수 덤프의 기능을 갖추고 있습니다. 예를 들어, 이하.

    printf( "%6D", ptr, "": ); gives "XX:XX:XX:XX:XX:XX"

    printf( "%*D", len, ptr, " " ); gives "XX XX XX ..."

캐릭터 테스트와 변환

    int isupper(int c)

    int islower(int c)

    int isspace(int c)

    int isdigit(int c)

    int isxdigit(int c)

    int isascii(int c)

    int isalpha(int c)

    int toupper(int c)

    int tolower(int c)

파일 입출력

    int open(const char *path, int flags)

    open(2) 의 동작을 닮아 있습니다. 다만, 파일 작성 기능이 서포트 되어 있지 않기 때문에, 모드 파라미터는 불필요합니다. 인수 flags 에는, O_RDONLY, O_WRONLY, O_RDWR 의 어떤 것인지를 지정할 수 있습니다. (비록, 현재 기록을 서포트하는 파일 시스템이 없다고 해도)

    int close(int fd)

    void closeall(void)

    모든 open 되고 있는 파일을 닫습니다.

    ssize_t read(int fd, void *buf, size_t len)

    ssize_t write(int fd, void *buf, size_t len)

    (현재 기입을 서로 서포트하고 있는 파일 시스템은 없습니다)

    off_t lseek(int fd, off_t offset, int whence)

    읽을 한중간에 자동적으로 해동되는 파일은, 현재의 위치에서 후방으로 seek 할 수 없습니다.

    int stat(const char *path, struct stat *sb)

    int fstat(int fd, struct stat *sb)

    함수 stat() 및 fstat() (은)는, sb 구조체의 필드 : st_mode, st_nlink, st_uid, st_gid, st_size 에의 기입만을 합니다. tftp 파일 시스템에서는, 이 함수의 호출은 의미가 있는 값이 되지 않습니다. 또 cd9660 파일 시스템은, 파일의 uid/gid 가 항상 0 이라고 보고해 옵니다.

페이쟈
libstand (은)는 간단한 내부 페이쟈를 제공해, 큰 명령의 출력을 읽기 쉽게 합니다.

    void pager_open()

    페이쟈를 초기화해, 다음의 출력행이 표시장치의 선두인 것을 알립니다. 환경 변수 LINES 는, 한 번에 표시 가능한 행수를 결정할 때에 참조됩니다.

    void pager_close(void)

    페이쟈를 닫습니다

    int pager_output(char *lines)

    lines 그리고 지정된, 눌로 종료하는 버퍼의 행이 페이쟈에 보내집니다. 개행 캐릭터를 세는 것으로, 출력되는 행수가 정해집니다. (즉시는 포함하지 않습니다) 모든 행이 출력되면(자), pager_output() (은)는 0 을 돌려줍니다. 화면 표시가 정지해, 유저가 도중 종료를 선택했을 때는 0 이외의 값을 돌려줍니다.

    int pager_file(char *fname)

    파일 fname (을)를 열어, 화면 표시합니다. 에러 때는 -1 (을)를 돌려주어, EOF 때는 0 을, 유저가 읽기를 도중 종료하는 경우는 1 을 돌려줍니다.

그 외

    void twiddle(void)

    연속 호출의 경우, 유저가 확인할 수 있도록(듯이), 캐릭터 라인 |,/,-,\ 의 후에 백 스페이스를 붙여 출력합니다.

저레벨 서포트의 요구
스택, heap, 콘솔, 디바이스는, libstand 그리고 잘 사용되는 리소스입니다.

스택은, libstand 함수가 기동되기 전에 구축할 필요가 있습니다. 스택 요구는, 함수나 사용되고 있는 파일 시스템, 및, 다음에 상술한다 서포트 레이어 함수에 의해 변화합니다.

heap는, alloc() 함수나 open() 함수의 호출 전에, setheap() 호출을 행해 구축하지 않으면 안됩니다. heap의 사용법은, 클라이언트의 동작과 같이, 동시에 open 하는 파일의 수에 의해 변화합니다. 자동 해동 와 파일을 open 할 때에 64K 이상의 데이터를 할당할 수 있습니다.

콘솔 액세스는, 후술의 함수 getchar(), putchar(), ischar() 에 의해 행해집니다.

디바이스 액세스는 devopen() 에 의해 초기화되어 devopen() 하지만 돌려주는 디바이스 스윗치 구조체의 함수 dv_strategy(), dv_ioctl(), dv_close() 에 의해 실행됩니다.

유저는 다음의 서포트 함수를 준비할 필요가 있습니다.

    int getchar(void)

    콘솔로부터, 함수 gets(), ngets() (이)나 페이쟈 함수에 의해 사용되는 캐릭터를 돌려줍니다.

    int ischar(void)

    콘솔로부터 입력 기다리는 상태 때, 0 이 아닌 값을 돌려줍니다.

    void putchar(int)

    콘솔에, gets(), ngets(), *printf(), panic(), twiddle() 및 다른 많은 디버그, 정보 통지용의 함수가 사용하는 문자를 써냅니다.

    int devopen(struct open_file *of, const char *name, char **file)

    name (이)라는 이름의 파일용의 적당한 디바이스를 열어, 디바이스를 참조하지 않는다 파일의 나머지의 부분의 name (을)를 가리키는 포인터를, file 에 돌려줍니다. of 의 구조체 필드 f_dev (은)는, 정상 종료했을 경우, open 한 디바이스의 devsw 구조체를 가리키도록(듯이) 세트 됩니다. 디바이스 식별자는, 항상 패스 구성의 선두에 온다 필요가 있습니다만, 그 이외는 자유롭게 포맷 되고 있습니다. open() (이)나 디바이스 관련의 I/O 로 사용됩니다.

    int devclose(struct open_file *of) of 에 할당할 수 있었던 디바이스를 닫습니다. 디바이스 드라이버-자신은 클로우즈 처리를 위해서(때문에) 벌써 호출을 하고 있어 이 호출은, devopen() 에 의한 할당을 해제할 뿐입니다.

    void panic(const char *msg, ...)

    치명적이어 회복 불능인 에러 상태를 통지합니다. 인수 msg ... (은)는, printf() 의 것과 같습니다.

내부 파일 시스템
내부 파일 시스템에서는, struct fs_ops *file_system[] 의 구조체의 배열을, 유저 하지만 export 할 수 있어 배열은 구조체 struct fs_ops 에의 포인터로 초기화됩니다. 이하의 파일 시스템 핸들러가 libstand 에 갖춰지고 있습니다만, 유저는 스스로 다른 파일 시스템을 제공할 수가 있습니다.

ufs_fsops
    BSD 의 UFS

ext2fs_fsops
    Linux 의 ext2fs 파일 시스템

tftp_fsops
    TFTP 경유의 파일 액세스

nfs_fsops
    NFS 경유의 파일 액세스

cd9660_fsops
    ISO 9660 (CD-ROM) 파일 시스템

zipfs_fsops
    파일을 서포트하고 있는 파일 시스템의 gzip 된 파일을 서포트하는 스택 된 파일 시스템으로, zipfs 파일 시스템을 사용하려고 하면(자), libstand (은)는 파일명의 뒤에 .gz (을)를 부가해, 더욱 다른 파일 시스템을 사용해 파일의 위치를 결정합니다. 이 파일 시스템의, 배열 file_system[] 에서의 배치에 의해, non-gzipped 파일을 참조하고 있는 gzipped 파일이 open 되는지 어떤지가 결정할 수 있습니다. gzip 된 파일은 전방에 seek 하는 것만이 할 수 있어 gzip 된 파일에의 stat() 및 fstat() (은)는, 길이의 부정을 보고합니다.

bzipfs_fsops
    zipfs_fsops (와)과 같습니다만, bzip2 그리고 압축된 파일을 사용합니다.

구조체 struct fs_ops 의 포인터 배열은 눌로 종료하지 않으면 안됩니다.

디바이스
디바이스는, 눌로 종료하는 디바이스 스윗치 구조체의 포인터 배열인, struct devsw *devsw[] 경유의 서포트 코드에 의해 export 됩니다.

버그
상세한 메모리 사용 데이터가 없는 것은 불친절합니다.

역사
libstand (은)는 많은 소스를 이용하고 있습니다. 즉,
•   NetBSD (으)로부터의 libsa
•   FreeBSD 3.0 (으)로부터의 libc (와)과 libkern
•   Matthew Dillon <dillon@backplane.com> (으)로부터의 zalloc

재구성과 FreeBSD 3.0 에의 포트, 환경 변수 관계의 함수, 이 메뉴얼 페이지는 Mike Smith <msmith@FreeBSD.org> 하지만 작성했습니다.