NAZWA

       ioctl - steruje urządzeniem

BIBLIOTEKA

       Standardowa biblioteka C (libc, -lc)

SKŁADNIA

       #include <sys/ioctl.h>

       int ioctl(int fd, unsigned long op, ...);  /* glibc, BSD */
       int ioctl(int fd, int op, ...);            /* musl, inny UNIX */

OPIS

       Wywołanie systemowe ioctl manipuluje na podległych jej parametrach urządzeń, do których dostęp odbywa się
       poprzez  pliki specjalne. W szczególności, za pomocą operacji ioctl() można kontrolować wiele właściwości
       operacyjnych specjalnych plików znakowych (np. terminali). Argument fd  musi  być  otwartym  deskryptorem
       pliku.

       Drugi  argument  jest  zależnym  od  urządzenia  kodem  operacji.  Trzeci  argument jest pozbawionym typu
       wskaźnikiem do obszaru pamięci, tradycyjnie char *argp (pochodzi z okresu zanim void * stało się poprawne
       w C) i tak będzie nazywany w niniejszej dyskusji.

       op Ioctl() zawiera w sobie zakodowaną informację czy argument jest parametrem wejściowym  czy  wyjściowym
       oraz  rozmiar  argp  tego argumentu w bajtach. Makra i definicje, używane do przekazywania op do ioctl(),
       znajdują się w pliku <sys/ioctl.h>. Zobacz UWAGI

WARTOŚĆ ZWRACANA

       Zazwyczaj, po pomyślnym zakończeniu zwracane jest  zero.  Niektóre  operacje  ioctl()  używają  zwracanej
       wartości  jako parametru wyjściowego i zwracają wówczas pewną wartość nieujemną. Po błędzie zwracane jest
       -1 i ustawiane errno wskazując błąd.

BŁĘDY

       EBADF  fd nie jest prawidłowym deskryptorem pliku.

       EFAULT argp wskazuje na niedostępny obszar pamięci.

       EINVAL op lub argp są nieprawidłowe.

       ENOTTY fd nie jest związane z urządzeniem znakowym.

       ENOTTY Podana operacja nie ma zastosowania do obiektu, na który wskazuje deskryptor fd.

WERSJE

       Argumenty, zwracane wartości i semantyka ioctl()  różnią  się  w  zależności  od  sterownika  urządzenia,
       którego  dotyczą  (wywołanie  jest  używane  jako  uniwersalne  dla  operacji,  które nie dają się ładnie
       dopasować do uniksowego modelu strumieni wejścia/wyjścia).

STANDARDY

       Brak.

HISTORIA

       Wersja 7 AT&T UNIX posiadała
           ioctl(int fildes, int op, struct sgttyb *argp);
       (gdzie struct sgttyb historycznie używane było przez stty(2) i gtty(2) i jest polimorficzne, zależnie  od
       typu operacji (podobnie, jak byłoby void *, gdyby było dostępne)).

       SysIII dokumentuje arg bez żadnego typu.

       4.3BSD miało
           ioctl(int d, unsigned long op, char *argp);
       (z char * podobnie jak w przypadku void *).

       SysVr4 miało
           int ioctl(int fildes, int op, ... /* arg */);

UWAGI

       Aby  używać niniejszego wywołanie, konieczny jest otwarty deskryptor pliku. Często wywołanie open(2) daje
       niepożądane skutki uboczne, którym pod Linuksem można zapobiec podając znacznik O_NONBLOCK.

   Struktura ioctl
       Wartości op ioctl są 32-bitowymi stałymi. Generalnie stałe te są zupełnie przypadkowe,  jednak  niektórzy
       próbują je jakoś strukturyzować.

       Wcześniej,  w  Linuksie  większość  16-bitowych  stałych składała się z ostatniego bajtu będącego numerem
       seryjnym i poprzedzającego go bajtu (bajtów) typu, który wskazuje sterownik.  Czasem  używany  był  numer
       główny:  0x03  do  ioctl HDIO_*, 0x06 do ioctl LP*. Czasem używana była również litera (lub kilka) ASCII.
       Przykładowo TCGETS ma wartość 0x00005401, z 0x54 = „T” wskazującym sterownik terminala, a CYGETTIMEOUT ma
       wartość 0x00435906, gdzie 0x43 0x59 = „C” „Y” wskazuje sterownik cyclades.

       Później (0.98p5) wbudowano w numer nieco więcej informacji. Miał on 2 bity kierunku (00: brak, 01: zapis,
       10: odczyt, 11: odczyt/zapis), po których następowało 14 bitów rozmiaru (wskazujących rozmiar argumentu),
       po których następował 8-bitowy typ (zbierający ioctl-e w grupy wg wspólnego  zastosowania  lub  wspólnego
       sterownika) i 8-bitowy numer seryjny.

       Makra    opisujące    tę    strukturę    istnieją   w   <asm/ioctl.h>   i   są   to   _IO(type,nr)   oraz
       {_IOR,_IOW,_IOWR}(type,nr,size). Używają sizeof(size), tak więc rozmiar  (size)  jest  tu  błędną  nazwą:
       trzeci argument jest typem danych.

       Proszę  zauważyć,  że  bity  rozmiaru  są  bardzo niepewne: w wielu przypadkach są nieprawidłowe, albo ze
       względu na błędne makra używające sizeof(sizeof(struct)), albo ze względu na przestarzałe wartości.

       Wszystko wskazuje zatem na to, że nowa struktura ma same wady:  nie  pomaga  w  sprawdzaniu,  a  powoduje
       zróżnicowanie wartości na różnych architekturach.

ZOBACZ TAKŻE

       execve(2),    fcntl(2),    ioctl_console(2),   ioctl_fat(2),   ioctl_ficlone(2),   ioctl_ficlonerange(2),
       ioctl_fideduperange(2), ioctl_fslabel(2), ioctl_getfsmap(2), ioctl_iflags(2), ioctl_ns(2),  ioctl_tty(2),
       ioctl_userfaultfd(2), open(2), sd(4), tty(4)

TŁUMACZENIE

       Autorami  polskiego  tłumaczenia  niniejszej  strony podręcznika są: Przemek Borys <pborys@dione.ids.pl>,
       Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl> i Michał Kułach <michal.kulach@gmail.com>

       Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje  o  warunkach  licencji  można  uzyskać
       zapoznając   się   z   GNU General Public License w wersji 3   lub  nowszej.  Nie  przyjmuje  się  ŻADNEJ
       ODPOWIEDZIALNOŚCI.

       Błędy w  tłumaczeniu  strony  podręcznika  prosimy  zgłaszać  na  adres  listy  dyskusyjnej  manpages-pl-
       list@lists.sourceforge.net.

Linux man-pages 6.8                              2 maja 2024 r.                                         ioctl(2)