"fcntl" --- The "fcntl" and "ioctl" system calls
************************************************

======================================================================

이 모듈은 파일 기술자에 대한 파일과 I/O 제어를 수행합니다. "fcntl()"과
"ioctl()" 유닉스 루틴에 대한 인터페이스입니다. 자세한 설명은
*fcntl(2)*과 *ioctl(2)* 유닉스 매뉴얼 페이지를 참조하십시오.

Availability: Unix, not Emscripten, not WASI.

이 모듈의 모든 함수는 첫 번째 인자로 파일 기술자 *fd*를 받아들입니다.
이것은 "sys.stdin.fileno()"에 의해 반환된 것과 같은 정수 파일 기술자이
거나 "sys.stdin" 자체와 같은 "io.IOBase" 객체일 수 있습니다. 이 객체는
실제 파일 기술자를 반환하는 "fileno()"를 제공합니다.

버전 3.3에서 변경: 이 모듈의 연산은 "IOError"를 발생시켰는데, 이제는
"OSError"를 발생시킵니다.

버전 3.8에서 변경: The fcntl module now contains "F_ADD_SEALS",
"F_GET_SEALS", and "F_SEAL_*" constants for sealing of
"os.memfd_create()" file descriptors.

버전 3.9에서 변경: On macOS, the fcntl module exposes the "F_GETPATH"
constant, which obtains the path of a file from a file descriptor. On
Linux(>=3.15), the fcntl module exposes the "F_OFD_GETLK",
"F_OFD_SETLK" and "F_OFD_SETLKW" constants, which are used when
working with open file description locks.

버전 3.10에서 변경: On Linux >= 2.6.11, the fcntl module exposes the
"F_GETPIPE_SZ" and "F_SETPIPE_SZ" constants, which allow to check and
modify a pipe's size respectively.

버전 3.11에서 변경: On FreeBSD, the fcntl module exposes the
"F_DUP2FD" and "F_DUP2FD_CLOEXEC" constants, which allow to duplicate
a file descriptor, the latter setting "FD_CLOEXEC" flag in addition.

이 모듈은 다음 함수를 정의합니다:

fcntl.fcntl(fd, cmd, arg=0)

   파일 기술자 *fd*("fileno()" 메서드를 제공하는 파일 객체도 허용됩니
   다)에 대해 *cmd* 연산을 수행합니다. *cmd*에 사용되는 값은 운영 체제
   에 따라 다르며, 관련 C 헤더 파일에 사용된 것과 같은 이름을 사용하여
   "fcntl" 모듈에서 상수로 제공됩니다. 인자 *arg*는 정숫값이나 "bytes"
   객체가 될 수 있습니다. 정숫값일 때, 이 함수의 반환 값은 C "fcntl()"
   호출의 정수 반환 값입니다. 인자가 바이트열일 때 바이너리 구조체를
   나타냅니다, 예를 들어 "struct.pack()"으로 만든 것입니다. 바이너리
   데이터는 주소가 C "fcntl()" 호출에 전달될 버퍼로 복사됩니다. 호출
   성공 후 반환 값은 버퍼 내용이며, "bytes" 객체로 변환됩니다. 반환된
   객체의 길이는 *arg* 인자의 길이와 같습니다. 이것은 1024바이트로 제
   한됩니다. 운영 체제에 의해 버퍼로 반환된 정보가 1024바이트보다 크면
   , 세그멘테이션 위반이나 더 미묘한 데이터 손상이 발생할 가능성이 큽
   니다.

   "fcntl()" 호출이 실패하면, "OSError"가 발생합니다.

   인자 "fd", "cmd", "arg"로 감사 이벤트 "fcntl.fcntl"을 발생시킵니다.

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

   이 함수는 인자 처리가 훨씬 더 복잡하다는 점을 제외하면, "fcntl()"
   함수와 같습니다.

   *request* 매개 변수는 32비트에 맞출 수 있는 값으로 제한됩니다.
   *request* 인자로 사용하기 위한 추가 상수는 관련 C 헤더 파일에서 사
   용된 것과 같은 이름으로 "termios" 모듈에서 제공됩니다.

   매개 변수 *arg*는 정수, 읽기 전용 버퍼 인터페이스를 지원하는
   ("bytes" 같은) 객체 또는 읽기-쓰기 버퍼 인터페이스를 지원하는
   ("bytearray" 같은) 객체 중 하나일 수 있습니다.

   마지막 경우를 제외하고는, 동작이 "fcntl()" 함수와 같습니다.

   가변 버퍼가 전달되면, 동작은 *mutate_flag* 매개 변수의 값에 의해 결
   정됩니다.

   거짓이면, 버퍼의 가변성은 무시되고 동작은 읽기 전용 버퍼일 때와 같
   습니다. 단, 위에서 언급한 1024바이트 제한은 피할 수 있습니다 -- 최
   소한 전달한 버퍼가 운영 체제가 원하는 만큼 길면 작동해야 합니다.

   *mutate_flag*가 참(기본값)이면, 버퍼가 (결과적으로) 하부 "ioctl()"
   시스템 호출로 전달되고, 이 호출의 반환 코드는 호출하는 파이썬으로
   다시 전달되고 버퍼의 새로운 내용은 "ioctl()"의 동작을 반영합니다.
   이것은 약간 단순화한 설명인데, 제공된 버퍼가 1024바이트보다 작으면,
   1024바이트 길이의 정적 버퍼에 먼저 복사된 다음, 이 정적 버퍼가
   "ioctl()"로 전달되고, 정적 버퍼를 제공된 버퍼로 다시 복사하기 때문
   입니다.

   "ioctl()" 호출이 실패하면, "OSError" 예외가 발생합니다.

   예제:

      >>> import array, fcntl, struct, termios, os
      >>> os.getpgrp()
      13341
      >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
      13341
      >>> buf = array.array('h', [0])
      >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
      0
      >>> buf
      array('h', [13341])

   인자 "fd", "request", "arg"로 감사 이벤트 "fcntl.ioctl"을 발생시킵
   니다.

fcntl.flock(fd, operation)

   파일 기술자 *fd*("fileno()" 메서드를 제공하는 파일 객체도 허용됩니
   다)에 대한 잠금 연산 *operation*을 수행합니다. 자세한 내용은 유닉스
   매뉴얼 *flock(2)*를 참조하십시오. (일부 시스템에서는, 이 함수가
   "fcntl()"를 사용하여 에뮬레이트됩니다.)

   "flock()" 호출이 실패하면, "OSError" 예외가 발생합니다.

   인자 "fd", "operation"으로 감사 이벤트 "fcntl.flock"을 발생시킵니다
   .

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

   이것은 본질에서 "fcntl()" 잠금 호출에 대한 래퍼입니다. *fd*는 잠그
   거나 잠금 해제할 파일의 파일 기술자이고 ("fileno()" 메서드를 제공하
   는 파일 객체도 허용됩니다), *cmd*는 다음 값 중 하나입니다:

   fcntl.LOCK_UN

      기존 잠금 해제.

   fcntl.LOCK_SH

      공유 잠금 획득.

   fcntl.LOCK_EX

      배타적 잠금 획득.

   fcntl.LOCK_NB

      다른 세 개의 "LOCK_*" 상수와 비트별 OR 하여 요청을 비 블로킹으로
      만듭니다.

   "LOCK_NB"가 사용되고 잠금을 얻을 수 없을 때, "OSError"가 발생하고
   *errno* 어트리뷰트가 "EACCES"나 "EAGAIN"으로 설정됩니다 (운영 체제
   에 따라 다릅니다; 이식성을 위해서 두 값을 모두 확인하십시오). 적어
   도 일부 시스템에서, "LOCK_EX"는 파일 기술자가 쓰기 위해 열린 파일을
   참조할 때만 사용할 수 있습니다.

   *len*은 잠글 바이트 수, *start*는 *whence*가 정의하는 기준으로 잠금
   이 시작되는 바이트 오프셋이며 *whence*는 "io.IOBase.seek()"에서와
   같은데, 구체적으로 다음과 같습니다:

   * "0" -- 파일의 시작에 상대적 ("os.SEEK_SET")

   * "1" -- 현재 버퍼 위치에 상대적 ("os.SEEK_CUR")

   * "2" -- 파일의 끝에 상대적 ("os.SEEK_END")

   *start*의 기본값은 파일 시작 부분에서 시작한다는 의미인 0입니다.
   *len*의 기본값은 파일 끝까지 잠그는 것을 의미하는 0입니다. *whence*
   의 기본값도 0입니다.

   인자 "fd", "cmd", "len", "start", "whence"로 감사 이벤트
   "fcntl.lockf"를 발생시킵니다.

예제 (모두 SVR4 호환 시스템에서):

   import struct, fcntl, os

   f = open(...)
   rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

   lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
   rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)

첫 번째 예제에서 반환 값 변수 *rv*는 정숫값을 저장합니다; 두 번째 예제
에서는 "bytes" 객체를 저장합니다. *lockdata* 변수에 대한 구조체 배치는
시스템 종속적입니다 --- 그래서 "flock()" 호출을 사용하는 것이 더 좋을
수 있습니다.

더 보기:

  모듈 "os"
     잠금 플래그 "O_SHLOCK"과 "O_EXLOCK"이 "os" 모듈에 있으면 (BSD에만
     해당합니다), "os.open()" 함수는 "lockf()"와 "flock()" 함수의 대안
     을 제공합니다.
