[UNIX] kqueue man page (macOS - BSD) 번역

*오역이 많을 수 있습니다. 직역과 의역을 섞어 번역되어 있어, 영문 문서를 기본으로 하되 참고하는 정도로 봐주시면 감사하겠습니다.*

 

 

 

man page 참조 환경:
macOS Big Sur 11.4
Apple clang version 12.0.5 (clang-1205.0.22.11)
Target: x86_64-apple-darwin20.5.0
Thread model: posix

 

 

 

 

KQUEUE(2)                        BSD System Calls Manual                          KQUEUE(2)

 

 

• NAME
  • kqueue, kevent, kevent64 and kevent_qos -- 커널 이벤트 발생 알림 매커니즘

• LIBRARY
  • Standard C Library (libc, -lc)

• SYNOPSIS

  • #include <sys/types.h>
    #include <sys/event.h>
    #include <sys/time.h>
    
    int kqueue(void);
    
    int kevent(int kq, const struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, const struct timespec *timeout);
    int kevent64(int kq, const struct kevent64_s *changelist, int nchanges, struct kevent64_s *eventlist, int nevents, unsigned int flags, const struct timespec *timeout);
    int kevent_qos(int kq, const struct kevent_qos_s *changelist, int nchanges, struct kevent_qos_s *eventlist, int nevents, void *data_out, size_t *data_available, unsigned int flags);
    
    EV_SET(&kev, ident, filter, flags, fflags, data, udata);
    EV_SET64(&kev, ident, filter, flags, fflags, data, udata, ext[0], ext[1]);
    EV_SET_QOS(&kev, ident, filter, flags, qos, udata, fflags, xflags, data, ext[0], ext[1], ext[2], ext[3]);

• DESCRIPTION
  • kqueue() 시스템 호출은 kqueue 파일 서술자를 할당합니다. 이 파일 서술자는 필터에 따라 사용자에게 커널 이벤트(kevent) 발생이나 조건과 일치하는 경우(condition holds)를 알아내는 메서드를 제공합니다.
  • kevent는 (ident, filter, 그리고 optional udata value) 튜플을 통해 식별됩니다. kevent는 이벤트 발생 시 알림을 받을 이벤트의 조건들을 정의합니다. (ident, filter, optional udata value)로 구성된 튜플은 kqueue 당 한 번만 존재할 수 있습니다. 주어진 kqueue에 대해 동일한 튜플을 등록하려는 후속 시도는 추가가 아니라 감시 중인 조건을 대체합니다. udata 값이 튜플의 일부로 간주되는지 여부는 kevent의 EV_UDATA_SPECIFIC flag에 의해 제어됩니다.
  • kevent에서 식별된 filter는 기존 condition이 있는지 여부를 감지하기 위해 해당 이벤트의 초기 등록 시 실행되며, 이벤트가 모니터링을 위해 filter에 전달될 때마다 실행됩니다. filter가 condition이 report되어야 한다고 결정되면 사용자가 검색할 수 있도록 kevent가 kqueue에 배치됩니다.
  • filter는 사용자가 kqueue에서 kevent를 검색하려고 할 때도 실행됩니다. filter가 이벤트를 발생시키는 조건이 더 이상 유지되지 않을 경우 kevent가 kqueue에서 제거되고 반환되지 않습니다.
  • 같은 filter로 여러 번 이벤트가 발생할 경우 kqueue에 여러 kevent가 배치되지 않습니다. 대신 필터는 이벤트를 단일 struct kevent로 집계합니다. 파일 디스크립터에서 close()를 호출하면 디스크립터를 참조하는 모든 kevent가 제거됩니다.
  • kqueue() 시스템 호출은 새 커널 이벤트 queue를 만들고 디스크립터를 반환합니다. queue는 fork(2)로 생성된 자식에게 상속되지 않습니다.
  • kevent,() kevent64() 및 kevent_qos() 시스템 호출은 queue에 이벤트를 등록하고, 보류 중인 이벤트를 사용자에게 반환하는 데 사용됩니다. changelist 인수는 <sys/event.h>에 정의된 대로 kevent, kevent64_s 또는 kevent_qos_s 구조의 배열에 대한 포인터입니다. changelist에 포함된 모든 변경 사항은 queue에서 보류 중인 이벤트를 읽기 전에 적용됩니다. nchanges 인수는 changelist의 크기를 전달합니다.
  • eventlist 인수는 반환되는 kevent, kevent64_s 또는 kevent_qos_s 구조체 배열에 대한 포인터입니다. nevents 인수는 eventlist 인수의 크기가 전달됩니다.
  • data_out 인수는 특정 filter에서 제공하는 추가 데이터를 위한 공간을 제공합니다. data_available 인수의 내용은 입력 시 데이터 풀에서 사용 가능한 공간을 지정했으며 출력 시 남아 있는 양을 포함합니다. KEVENT_FLAG_STACK_DATA 플래그가 시스템 호출에 지정되면 일반적인 힙 순서가 아닌 스택 순서로 풀에서 데이터가 할당됩니다.
  • timeout이 NULL이 아닌 포인터인 경우 이벤터를 기다리는 최대 interval을 지정하며 이는 구조체 timespec으로 해석됩니다. timeout이 NULL 포인터인 경우 kevent() 및 kevent64()는 무한정 대기합니다. polling을 수행하기 위해 kevent64() 또는 kevent_qos()에 대한 flag 인수에 KEVENT_FLAG_IMMEDIATE 값을 전달하여 즉시 종료(immediate timeout)할 수 있습니다. 또는 timeout 인수는 값이 0인 timespec 구조를 가리키는 non-NULL 포인터이어야 합니다. changelist와 eventlist에는 동일한 배열을 사용할 수 있습니다.
  • EV_SET() 매크로는 kevent 구조체를 쉽게 초기화하기 위해 제공됩니다. 마찬가지로 EV_SET64()는 kevent64_s 구조체를 초기화하고 EV_SET_QOS()는 kevent_qos_s 구조체를 초기화합니다.
  • kevent, kevent64_s, 그리고 kevent_qos_s 구조체는 다음과 같이 정의되어 있습니다:

  • struct kevent
    {
        uintptr_t ident; /* 이벤트 식별자 (identifier for this event) */
        int16_t filter; /* 이벤트 필터 (filter for event) */
        uint16_t flags; /* 일반 플래그 (general flags) */
        uint32_t fflags; /* 필터 플래그 (filter-specific flags) */
        intptr_t data; /* 필터 데이터 (filter-specific data) */
        void *udata; /* 사용자 데이터 (opaque user data identifier) */
    };
    
    struct kevent64_s
    {
        uint64_t ident; /* 이벤트 식별자 (identifier for this event) */
        int16_t filter; /* 이벤트 필터 (filter for event) */
        uint16_t flags; /* 일반 플래그 (general flags) */
        uint32_t fflags; /* 필터 플래그 (filter-specific flags) */
        int64_t data; /* 필터 데이터 (filter-specific data) */
        uint64_t udata; /* 사용자 데이터 (opaque user data identifier) */
        uint64_t ext[2]; /* 필터 확장 (filter-specific extensions) */
    };
    
    struct kevent_qos_s
    {
        uint64_t ident; /* 이벤트 식별자 (identifier for this event) */
        int16_t filter; /* 이벤트 필터 (filter for event) */
        uint16_t flags; /* 일반 플래그 (general flags) */
        uint32_t qos; /* quality of service when servicing event */
        uint64_t udata; /* 사용자 데이터 (opaque user data identifier) */
        uint32_t fflags; /* 필터 플래그 (filter-specific flags) */
        uint32_t xflags; /* 추가 필터 플래그 (extra filter-specific flags) */
        int64_t data; /* 필터 데이터 (filter-specific data) */
        uint64_t ext[4]; /* 필터 확장 (filter-specific extensions) */
    };

• kevent, kevent64_s, kevent_qos_s 구조체의 필드들은 다음과 같습니다:
  • ident 이벤트의 source를 식별하는 데 사용되는 값입니다. 정확한 해석은 filter 의해 결정되지만, 주로 파일 디스크립터를 통해 결정됩니다.
  • filter 이 이벤트를 처리하는 데 사용되는 커널 필터를 식별합니다. 사전 정의된 시스템 필터는 아래에 설명되어 있습니다.
  • flags 이벤트에서 수행될 작업입니다.
  • fflags 필터에 따른 플래그입니다.
  • data 필터에 따른 데이터입니다.
  • udata 커널을 통해 전달된 불투명한 사용자 정의 값은 변경되지 않습니다. 선택적으로 kevent 시스템의 고유한 결정의 일부가 될 수 있습니다.
• 추가로, kevent_64_s 구조체는 다음을 포함합니다:
  • ext[2] 이 필드는 이벤트 필터에 대한 확장을 저장합니다. 확장 유형은 사용 중인 필터에 따라 다릅니다.
• 추가로, kevent_qos_s 구조체는 다음을 포함합니다:
  • xflags 추가(Extra) 필터별 플래그입니다.
  • ext[4] QoS 변형은 필터별 사용을 위해 두 배 더 많은 확장 값을 제공합니다.
• flag는 다음의 값을 포함할 수 있습니다:
  • EV_ADD 이벤트를 kqueue에 추가합니다. 기존에 존재하는 이벤트를 다시 추가하면 원래 이벤트의 매개변수가 수정되며, 중복 항목이 생성되지 않습니다. EV_DISABLE 플래그로 재정의되지 않는 한 이벤트를 추가하면 자동으로 활성화됩니다.
  • EV_ENABLE kevent(), kevent64(), kevent_pos()가 이벤트 발생 시 반환할 수 있도록 허용합니다.
  • EV_DISABLE 이벤트를 비활성화하여 kevent(), kevent64(), kevent_qos()가 이벤트를 반환하지 않습니다. 이 필터 자체는 비활성화되지 않습니다.
  • EV_DELETE kqueue에서 이벤트를 제거합니다. 파일 디스크립터를 참조하는 이벤트는 디스크립터가 마지막으로 닫힐 때(close) 자동으로 삭제됩니다.
  • EV_RECEIPT 이 플래그는 보류 중인 이벤트를 소모하지 않고 kqueue를 대량으로 변경하는 데 유용합니다. 입력으로 전달되면 EV_ERROR가 항상 반환되도록 합니다. 필터가 성공적으로 추가되면 data 필드는 0이 됩니다.
  • EV_ONESHOT 해당 이벤터가 처음 발생한 경우에만 반환하도록 합니다. 사용자가 kqueue에서 이벤트를 검색한 후 삭제됩니다.
  • EV_CLEAR 사용자가 이벤트를 검색한 후 상태가 리셋됩니다. 이것은 현재 상태 대신 상태 전환을 보고하는 필터에 유용합니다. 일부 필터는 내부적으로 이 플래그를 자동으로 설정할 수 있습니다.
  • EV_EOF 필터에 따라 EOF 조건을 나타내기 위해 설정될 수 있습니다.
  • EV_OOBAND 소켓의 read 필터는 디스크립터에 대역 외 데이터(out of band data)가 있음을 나타내기 위해 이 플래그를 설정할 수 있습니다.
  • EV_ERROR 아래의 RETURN VALUES를 참고하세요.
• 사전 정의된 시스템 필터는 다음과 같습니다. data와 fflags, 그리고 kevent64_s와 kevent_qos_s 구조체의 경우 xflags 필드는 필터에 따라 따라 인자가 전달됩니다.
  • EVFILT_READ
    • 파일 설명자를 식별자로 사용하고 읽을 수 있는 데이터가 있을 때마다 반환합니다. 필터의 동작은 설명자 유형에 따라 약간 다릅니다.
    • Sockets
      • listen()에 전달되었던 소켓은 들어오는 연결이 보류 중일 때 반환됩니다. 데이터에는 listen backlog의 크기가 포함됩니다.
      • 다른 소켓 디스크립터는 소켓 버퍼의 SO_RCVLOWAT 값에 따라 읽을 데이터가 있을 때 반환됩니다. 이는 fflags에 NOTE_LOWAT 플래그를 설정하고 데이터에 새로운 하위 워터마크를 지정하여 필터가 추가될 때 필터별 하위 워터마크로 재정의될 수 있습니다. 그러나 파생된 필터당 로우 워터 마크 값은 소켓 수신 버퍼의 하이 및 로우 워터 마크 값으로 제한됩니다. 반환 시 data에는 읽을 수 있는 프로토콜 데이터의 바이트 수가 저장됩니다.
      • 플래그에 EV_OOBAND가 있으면 읽을 수 있는 잠재적인 OOB 바이트 수와 동일한 소켓 데이터에 대역 외 데이터가 있음을 나타냅니다.
      • 소켓의 읽기 방향이 종료된 경우 필터는 플래그에 EV_EOF도 설정하고 fflags에 소켓 오류를 반환합니다. 소켓 버퍼에 보류 중인 데이터가 아직 있는 동안 EOF가 반환될 수 있습니다(연결이 끊어졌음을 나타냄).
    • Vnodes
      • 파일 포인터가 파일의 끝이 아닌 경우 반환합니다. 데이터는 현재 위치에서 파일 끝까지의 오프셋을 포함하며 음수일 수 있습니다.
    • Fifos, Pipes
      • 읽을 데이터가 있을 때 반환합니다. data는 사용 가능한 바이트 수가 저장됩니다.
      • 마지막 writer가 연결을 끊으면 filter가 flags에 EV_EOF를 설정합니다. 이것은 EV_CLEAR를 전달하여 지울 수 있으며, 이 시점에서 filter는 반환하기 전에 데이터를 사용할 수 있을 때까지 계속 대기합니다.
    • Device nodes
      • device에서 읽을 데이터가 있으면 반환합니다. data는 사용 가능한 바이트 수가 저장됩니다. device가 바이트 수 반환을 지원하지 않는 경우 필터 사용을 허용하지 않습니다. 그러나 NOTE_LOWAT flag가 지정되고 data필드에 입력 시 1이 포함된 경우 해당 장치가 연결되지만, 출력 시 읽을 정확한 바이트 수를 제공하지 않습니다.
  • EVFILT_EXCEPT
    • 디스크립터를 식별자로 사용하고 설명자에서 지정된 예외 조건 중 하나가 발생할 때마다 반환합니다. 조건은 fflags에 지정됩니다. 현재 이 필터는 필터 플래그 NOTE_OOB를 사용하여 소켓 설명자에 대한 대역외 데이터(out-of-band data)의 도착을 모니터링하는 데 사용할 수 있습니다.
    • 소켓의 읽기 방향이 종료된 경우 필터는 flags에 EV_EOF도 설정하고 fflags에 소켓 오류(있는 경우)를 반환합니다.
  • EVFILT_WRITE
    • 파일 디스크립터를 식별자로 사용하고 디스크립터에 write할 수 있을 때마다 반환합니다. 소켓, pipe 및 fifo의 경우 data에는 쓰기 버퍼에 남아 있는 공간이 포함됩니다. 이 filter는 reader가가 연결 해제될 때 EV_EOF를 설정하고 fifo의 경우 EV_CLEAR를 사용하여 이를 지울 수 있습니다. 이 필터는 vnode에 대해 지원되지 않습니다.
    • 소켓의 경우 로우 워터마크 및 소켓 에러 처리는 EVFILT_READ와 동일합니다.
  • EVFILT_AIO
    • 이 필터는 현재 지원되지 않습니다.
  • EVFILT_VNODE
    • 파일 디스크립터를 식별자로 사용하고 fflags에서 감시할 이벤트를 사용하며, 디스크립터에서 요청된 이벤트 중 하나 이상이 발생할 때 반환합니다. 모니터링할 이벤트는 다음과 같습니다.
      • NOTE_DELETE 디스크립터가 참조하는 파일에서 unlink() 시스템 호출이 호출되었습니다.
      • NOTE_WRITE 디스크립터가 참조하는 파일에 쓰기가 발생했습니다.
      • NOTE_EXTEND 디스크립터가 참조하는 파일이 확장되었습니다.
      • NOTE_ATTRIB 디스크립터가 참조하는 파일의 속성이 변경되었습니다.
      • NOTE_LINK 파일의 링크 수가 변경되었습니다.
      • NOTE_RENAME 디스크립터가 참조하는 파일의 이름이 변경되었습니다.
      • NOTE_REVOKE 파일에 대한 접근이 revoke(2)에 의해 취소되었거나 파일 시스템이 해제되었습니다.
      • NOTE_FUNLOCK 파일이 close(2) 또는 flock(2)에 의해 해제되었습니다.
    • 반환 시 fflags에는 이 필터에 의해 표시되는 트리거된 이벤트와 관련된 필터별 플래그가 포함됩니다.
  • EVFILT_PROC
    • 모니터링할 프로세스 ID를 식별자로, fflags를 감시할 이벤트로 사용하고, 프로세스가 요청된 이벤트 중 하나 이상을 수행할 때 반환합니다. 프로세스가 일반적으로 다른 프로세스를 볼 수 있는 경우 이벤트를 연결할 수 있습니다. 모니터링할 이벤트는 다음과 같습니다.
      • NOTE_EXIT 프로세스가 종료되었습니다.
      • NOTE_EXITSTATUS 프로세스가 종료되고, data에 exit status가 저장됩니다. 자식 프로세스에게 NOTE_EXIT와 같이 사용될 때만 유효합니다.
      • NOTE_FORK 프로세스가 fork(2)나 유사한 호출을 통해 자식 프로세스를 생성했습니다.
      • NOTE_EXEC 프로세스가 execve(2)나 유사한 호출을 통해 새로운 프로세스를 실행했습니다.
      • NOTE_SIGNAL 프로세스에 시그널이 전송되었습니다. waitpid(2)나 유사한 호출을 통해 상태를 확인할 수 있습니다.
      • NOTE_REAP wait(2) 또는 유사한 호출을 통해 부모에게 회수되었습니다. 이 이벤트는 사용되지 않습니다. NOTE_EXIT를 사용하세요.
    • 반환 시 fflags에는 필터를 트리거한 이벤트가 담깁니다.
  • EVFILT_SIGNAL
    • 모니터링할 시그널 번호를 식별자로 사용하고 지정된 시그널이 프로세스에 대해 생성될 때 반환됩니다. 이것은 signal() 및 sigaction() 기능과 공존하며 우선 순위가 낮습니다. 특정 스레드가 아닌 프로세스로 전송된 신호만 필터를 트리거합니다. 필터는 시그널이 SIG_IGN으로 표시된 경우에도 프로세스에 시그널을 전달하려는 모든 시도를 기록합니다. 이벤트 알림은 정상적인 신호 전달 처리 전에 발생합니다. data는 kevent()에 대한 마지막 호출 이후 시그널이 생성된 횟수를 반환합니다. 이 필터는 내부적으로 EV_CLEAR 플래그를 자동으로 설정합니다.
  • EVFILT_MACHPORT
    • mach port의 이름이나 port set을 식별자로 받고, 메시지가 큐에 삽입될 때까지 대기합니다. 메시지가 인식되고, kevent 호출이 이루어지지 않은 경우, 메시지가 도착한 특정 포트의 이름이 data에 반환됩니다. fflag에 MACH_RCV_MSG가 저장될 경우, ext[0]과 ext[1] flag는 메시지를 수신할 버퍼에 대한 포인터와 수신 버퍼의 크기를 각각 포함하는 것으로 가정합니다. 만약 MACH_RCV_MSG가 지정되어 있으나 ext[1]의 버퍼 크기가 0이면, kevent_qos()에 제공된 data_out 영역에 충분한 공간이 남아 있는 경우 data_out에 저장될 수 있습니다.
  • EVFILT_TIMER
    • ident를 식별자로 하고, data를 간격(밀리초 단위)의 타임아웃 인터벌 타이머를 설정합니다.
    • 다른 타이머 유닛을 식별하기 위해 fflag는 다음 중 하나의 flag를 가질 수 있습니다.
      • NOTE_SECONDS data가 초 단위일 경우
      • NOTE_USECONDS data가 마이크로초 단위일 경우
      • NOTE_NSECONDS data가 나노초 단위일 경우
      • NOTE_MACHTIME data가 mach_absolute_time 단위일 경우
    • 플래그에는 간격 대신 절대 기한으로 EV_ONESHOT 타이머를 설정하는 NOTE_ABSOLUTE도 포함될 수 있습니다. 절대 기한은 gettimeofday(2)로 표현됩니다. NOTE_MACHTIME을 사용하면 데드라인은 mach_absolute_time()으로 표현됩니다.
    • 타이머는 다른 타이머와 병합하여 power를 절약할 수 있습니다. 이 동작을 수정하기 위해 fflags에 다음 플래그를 설정할 수 있습니다.
      • NOTE_CRITICAL 여유 값을 보다 엄격하게 준수하기 위해 기본 절전 기술을 덮어씁니다.
      • NOTE_BACKGROUND 이 타이머를 다른 타이머와 병합하기 위해 더 많은 절전 기술을 적용합니다.
      • NOTE_LEEWAY ext[1]은 타이머 통합을 위하여 사용자 제공 슬롭을 보유합니다.
    • EV_ONESHOT이 지정되지 않는 한 타이머는 주기적입니다. 반환 시 데이터에는 타이머 이벤트의 마지막 준비 또는 마지막 전달 이후 시간 초과가 만료된 횟수가 포함됩니다.
    • 이 filter는 자동으로 EV_CLEAR flag를 설정합니다.
• kevent64_s 구조체의 ext[2] 필드에서 ext[0]은 EVFILT_MACHPORT filter에만 사용됩니다. 다른 filter를 사용하면 ext[0]이 udata처럼 kevent64()를 통해 전달됩니다. ext[1]은 항상 udata처럼 사용할 수 있습니다. ext[0]의 사용에 대해서는 위의 EVFILT_MACHPORT 필터를 참조하십시오.

• RETURN VALUES
  • kqueue() 시스템 호출은 새 커널 이벤트 큐를 만들고 파일 디스크립터를 반환합니다. 커널 이벤트 큐를 생성하는 동안 오류가 발생했다면 -1 값이 반환되고 errno가 설정됩니다.
  • kevent(), kevent64() 및 kevent_qos() 시스템 호출은 eventlist에 있는 이벤트 수를 최대 nevents에 의해 제공된 값까지 반환합니다. changelist의 요소를 처리하는 동안 오류가 발생하고 eventlist에 충분한 공간이 있는 경우 이벤트는 플래그에 설정된 EV_ERROR 및 데이터의 시스템 오류와 함께 이벤트 목록에 배치됩니다. 그렇지 않으면 -1이 반환되고 errno가 오류 조건을 나타내도록 설정됩니다. timeout이 만료되면 kevent(), kevent64() 및 kevent_qos()가 0을 반환합니다.
• ERRORS
  • kqueue() 시스템 호출은 다음과 같은 상황에서 실패합니다:
    • [ENOMEM] 커널 큐를 위한 메모리 할당에 실패했습니다.
    • [EMFILE] 프로세스 디스크립터 테이블이 가득 찼습니다.
    • [ENFILE] 시스템 파일 테이블이 가득 찼습니다.
  • The kevent()와 kevent64() 시스템 호출은 다음과 같은 상황에서 실패합니다:
    • [EACCES] 프로세스가 filter를 등록하기 위한 권한이 없습니다.
    • [EFAULT] kevent 또는 kevent64_s를 읽거나 쓰는데 오류가 발생했습니다.
    • [EBADF] 디스크립터가 유효하지 않습니다.
    • [EINTR] 타임아웃 만료 또는 이벤트가 배치되기 전 시그널이 전달되었습니다.
    • [EINVAL] filte가 유효하지 않습니다.
    • [ENOENT] 이벤트를 수정하거나 삭제할 수 없습니다.
    • [ENOMEM] 이벤트를 등록하기 위한 메모리가 부족합니다.
    • [ESRCH] 지정된 프로세스가 존재하지 않습니다.
• SEE ALSO
  • aio_error(2), aio_read(2), aio_return(2), read(2), select(2), sigaction(2), write(2), signal(3)
• HISTORY
  • kqueue()와 kevent() 시스템 호출은 FreeBSD 4.1에서 처음 등장했습니다.
• AUTHORS
  • kqueue() 시스템과 매뉴얼 페이지는 Jonathan Lemon에 의해 쓰였습니다. jlemon@FreeBSD.org.
• BUGS
  • 모든 파일 시스템 유형이 kqueue 스타일 알림을 지원하는 것은 아닙니다. 그리고 일부 원격 파일 시스템과 마찬가지로 일부는 여기에 설명된 알림 의미의 하위 집합만 지원할 수 있습니다.

BSD                                October 21, 2008                                  BSD