# `fcntl` — The `fcntl` and `ioctl` system calls

This module performs file and I/O control on file descriptors. It is an interface to the `fcntl()` and `ioctl()` Unix routines. See the fcntl(2) and ioctl(2) Unix manual pages for full details.

Availability: Unix, 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.

버전 3.12에서 변경: On Linux >= 4.5, the `fcntl` module exposes the `FICLONE` and `FICLONERANGE` constants, which allow to share some data of one file with another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and XFS). This behavior is commonly referred to as “copy-on-write”.

버전 3.13에서 변경: On Linux >= 2.6.32, the `fcntl` module exposes the `F_GETOWN_EX`, `F_SETOWN_EX`, `F_OWNER_TID`, `F_OWNER_PID`, `F_OWNER_PGRP` constants, which allow to direct I/O availability signals to a specific thread, process, or process group. On Linux >= 4.13, the `fcntl` module exposes the `F_GET_RW_HINT`, `F_SET_RW_HINT`, `F_GET_FILE_RW_HINT`, `F_SET_FILE_RW_HINT`, and `RWH_WRITE_LIFE_*` constants, which allow to inform the kernel about the relative expected lifetime of writes on a given inode or via a particular open file description. On Linux >= 5.1 and NetBSD, the `fcntl` module exposes the `F_SEAL_FUTURE_WRITE` constant for use with `F_ADD_SEALS` and `F_GET_SEALS` operations. On FreeBSD, the `fcntl` module exposes the `F_READAHEAD`, `F_ISUNIONSTACK`, and `F_KINFO` constants. On macOS and FreeBSD, the `fcntl` module exposes the `F_RDAHEAD` constant. On NetBSD and AIX, the `fcntl` module exposes the `F_CLOSEM` constant. On NetBSD, the `fcntl` module exposes the `F_MAXFD` constant. On macOS and NetBSD, the `fcntl` module exposes the `F_GETNOSIGPIPE` and `F_SETNOSIGPIPE` constant.

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

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

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

  If the `fcntl()` call fails, an `OSError` is raised.

  인자 `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()`로 전달되고, 정적 버퍼를 제공된 버퍼로 다시 복사하기 때문입니다.

  If the `ioctl()` call fails, an `OSError` exception is raised.

  예제:

      >>> 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()`를 사용하여 에뮬레이트됩니다.)

  If the `flock()` call fails, an `OSError` exception is raised.

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

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

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

  fcntl.LOCK_UN

    Release an existing lock.

  fcntl.LOCK_SH

    Acquire a shared lock.

  fcntl.LOCK_EX

    Acquire an exclusive lock.

  fcntl.LOCK_NB

    Bitwise OR with any of the other three `LOCK_*` constants to make the request non-blocking.

  If `LOCK_NB` is used and the lock cannot be acquired, an `OSError` will be raised and the exception will have an errno attribute set to `EACCES` or `EAGAIN` (depending on the operating system; for portability, check for both values). On at least some systems, `LOCK_EX` can only be used if the file descriptor refers to a file opened for writing.

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

  - `0` – relative to the start of the file (`os.SEEK_SET`)

  - `1` – relative to the current buffer position (`os.SEEK_CUR`)

  - `2` – relative to the end of the file (`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`

  If the locking flags `O_SHLOCK` and `O_EXLOCK` are present in the `os` module (on BSD only), the `os.open()` function provides an alternative to the `lockf()` and `flock()` functions.