fcntl — Systemanropen fcntl och ioctl

Den här modulen utför fil- och I/O-kontroll på filbeskrivare. Den är ett gränssnitt till Unix-rutinerna fcntl() och ioctl(). Se Unix manualsidor fcntl(2) och ioctl(2) för fullständig information.

Tillgänglighet: Unix, not WASI.

Alla funktioner i denna modul tar en filbeskrivare fd som sitt första argument. Detta kan vara en heltalsfilbeskrivning, som den som returneras av sys.stdin.fileno(), eller ett io.IOBase-objekt, som sys.stdin själv, som tillhandahåller en fileno() som returnerar en äkta filbeskrivning.

Ändrad i version 3.3: Operationer i denna modul brukade ge upphov till ett IOError, men nu ger de upphov till ett OSError.

Ändrad i version 3.8: Modulen fcntl innehåller nu konstanterna F_ADD_SEALS, F_GET_SEALS och F_SEAL_* för försegling av os.memfd_create()-filbeskrivare.

Ändrad i version 3.9: På macOS exponerar modulen fcntl konstanten F_GETPATH, som erhåller sökvägen till en fil från en filbeskrivare. På Linux (>=3.15) exponerar modulen fcntl konstanterna F_OFD_GETLK, F_OFD_SETLK och F_OFD_SETLKW, som används när man arbetar med öppna filbeskrivningslås.

Ändrad i version 3.10: På Linux >= 2.6.11, exponerar modulen fcntl konstanterna F_GETPIPE_SZ och F_SETPIPE_SZ, som gör det möjligt att kontrollera respektive ändra en pipes storlek.

Ändrad i version 3.11: På FreeBSD exponerar fcntl-modulen konstanterna F_DUP2FD och F_DUP2FD_CLOEXEC, som gör det möjligt att duplicera en filbeskrivare, den senare sätter dessutom flaggan FD_CLOEXEC.

Ändrad i version 3.12: På Linux >= 4.5, exponerar fcntl-modulen konstanterna FICLONE och FICLONERANGE, som gör det möjligt att dela vissa data i en fil med en annan fil genom att återlänka på vissa filsystem (t.ex. btrfs, OCFS2 och XFS). Detta beteende kallas vanligen ”copy-on-write”.

Ändrad i version 3.13: På Linux >= 2.6.32, exponerar fcntl-modulen konstanterna F_GETOWN_EX, F_SETOWN_EX, F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP, som gör det möjligt att rikta I/O-tillgänglighetssignaler till en specifik tråd, process eller processgrupp. På Linux >= 4.13 exponerar modulen fcntl konstanterna F_GET_RW_HINT, F_SET_RW_HINT, F_GET_FILE_RW_HINT, F_SET_FILE_RW_HINT och RWH_WRITE_LIFE_*, som gör det möjligt att informera kärnan om den relativa förväntade livslängden för skrivningar på en viss inode eller via en viss beskrivning av en öppen fil. På Linux >= 5.1 och NetBSD, exponerar modulen fcntl konstanten F_SEAL_FUTURE_WRITE för användning med F_ADD_SEALS och F_GET_SEALS operationer. På FreeBSD exponerar modulen fcntl konstanterna F_READAHEAD, F_ISUNIONSTACK och F_KINFO. På macOS och FreeBSD exponerar modulen fcntl konstanten F_RDAHEAD. På NetBSD och AIX exponerar modulen fcntl konstanten F_CLOSEM. På NetBSD exponerar modulen fcntl konstanten F_MAXFD. På macOS och NetBSD exponerar modulen fcntl konstanterna F_GETNOSIGPIPE och F_SETNOSIGPIPE.

Ändrad i version 3.14: På Linux >= 6.1 exponerar modulen fcntl modulen F_DUPFD_QUERY för att fråga en filbeskrivare som pekar på samma fil.

Modulen definierar följande funktioner:

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

Utför operationen cmd på filbeskrivaren fd (filobjekt som tillhandahåller en fileno()-metod accepteras också). De värden som används för cmd är beroende av operativsystemet och finns tillgängliga som konstanter i modulen fcntl, med samma namn som används i de relevanta C-headerfilerna. Argumentet arg kan antingen vara ett heltalsvärde, ett bytesliknande objekt eller en sträng. Typ och storlek på arg måste överensstämma med typ och storlek på argumentet för operationen enligt specifikationen i relevant C-dokumentation.

När arg är ett heltal, returnerar funktionen heltalsreturvärdet för anropet C fcntl().

När argumentet är ett bytesliknande objekt representerar det en binär struktur, t.ex. skapad av struct.pack(). Ett strängvärde kodas till binär med hjälp av UTF-8-kodning. De binära data kopieras till en buffert vars adress skickas till C fcntl()-anropet. Returvärdet efter ett lyckat anrop är innehållet i bufferten, konverterat till ett bytes-objekt. Längden på det returnerade objektet kommer att vara densamma som längden på argumentet arg. Detta är begränsat till 1024 byte.

Om anropet av fcntl() misslyckas, genereras ett OSError.

Anteckning

Om typen eller storleken på arg inte stämmer överens med typen eller storleken på argumentet för operationen (t.ex. om ett heltal skickas när en pekare förväntas, eller om informationen som returneras i bufferten av operativsystemet är större än 1024 byte), är det mest troligt att detta resulterar i en segmenteringsöverträdelse eller en mer subtil datakorruption.

Utlöser en auditing event fcntl.fcntl med argumenten fd, cmd, arg.

Ändrad i version 3.14: Lägg till stöd för godtyckliga bytesliknande objekt, inte bara bytes.

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

Denna funktion är identisk med funktionen fcntl(), förutom att argumenthanteringen är ännu mer komplicerad.

Parametern request är begränsad till värden som kan rymmas i 32-bitar eller 64-bitar, beroende på plattform. Ytterligare konstanter av intresse för användning som request-argument finns i modulen termios, under samma namn som används i de relevanta C-headerfilerna.

Parametern arg kan vara ett heltal, ett bytesliknande objekt eller en sträng. Typ och storlek på arg måste överensstämma med typ och storlek på argumentet för operationen enligt vad som anges i relevant C-dokumentation.

Om arg inte stöder gränssnittet för skriv-läs-buffert eller om mutate_flag är false, är beteendet detsamma som för funktionen fcntl().

Om arg stöder gränssnittet för skriv-läs-buffertar (som bytearray) och mutate_flag är true (standard), då skickas bufferten (i praktiken) till det underliggande systemanropet ioctl(), den senares returkod skickas tillbaka till den anropande Python, och buffertens nya innehåll återspeglar åtgärden från ioctl(). Detta är en liten förenkling, för om den medföljande bufferten är mindre än 1024 byte lång kopieras den först till en statisk buffert som är 1024 byte lång, som sedan skickas till ioctl() och kopieras tillbaka till den medföljande bufferten.

Om anropet av ioctl() misslyckas, uppstår ett undantag av typen OSError.

Anteckning

Om typen eller storleken på arg inte stämmer överens med typen eller storleken på operationens argument (t.ex. om ett heltal skickas när en pekare förväntas, eller om informationen som returneras i bufferten av operativsystemet är större än 1024 byte, eller om storleken på det byte-liknande objektet är för liten), är det mest troligt att detta resulterar i en segmenteringsöverträdelse eller en mer subtil datakorruption.

Ett exempel:

>>> 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])

Utlöser en auditing event fcntl.ioctl med argumenten fd, request, arg.

Ändrad i version 3.14: GIL frigörs alltid under ett systemanrop. Systemanrop som misslyckas med EINTR försöker automatiskt på nytt.

fcntl.flock(fd, operation, /)

Utför låsoperationen operation på filbeskrivaren fd (filobjekt som tillhandahåller en fileno()-metod accepteras också). Se Unix-manualen flock(2) för mer information. (På vissa system emuleras denna funktion med hjälp av fcntl())

Om anropet av flock() misslyckas, uppstår ett undantag av typen OSError.

Utlöser en auditing event fcntl.flock med argumenten fd, operation.

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

Detta är i huvudsak ett omslag runt fcntl() låsningsanrop. fd är filbeskrivaren (filobjekt som tillhandahåller en fileno()-metod accepteras också) för den fil som ska låsas eller låsas upp, och cmd är ett av följande värden:

fcntl.LOCK_UN

Frigör ett befintligt lås.

fcntl.LOCK_SH

Förvärva ett delat lås.

fcntl.LOCK_EX

Förvärva ett exklusivt lås.

fcntl.LOCK_NB

Bitvis OR med någon av de andra tre LOCK_*-konstanterna för att göra begäran icke-blockerande.

Om LOCK_NB används och låset inte kan förvärvas, kommer ett OSError att uppstå och undantaget kommer att ha ett errno-attribut satt till EACCES eller EAGAIN (beroende på operativsystem; för portabilitet, kontrollera båda värdena). På åtminstone vissa system kan LOCK_EX endast användas om filbeskrivaren hänvisar till en fil som är öppen för skrivning.

len är antalet byte som ska låsas, start är den byteoffset som låset startar vid, relativt whence, och whence är som med io.IOBase.seek(), specifikt:

  • 0 – relativt till början av filen (os.SEEK_SET)

  • 1 – relativt den aktuella buffertpositionen (os.SEEK_CUR)

  • 2 – i förhållande till slutet av filen (os.SEEK_END)

Standardvärdet för start är 0, vilket innebär att man börjar i början av filen. Standardvärdet för len är 0, vilket innebär att man låser till slutet av filen. Standardvärdet för whence är också 0.

Utlöser en auditing event fcntl.lockf med argumenten fd, cmd, len, start, whence.

Exempel (alla på ett SVR4-kompatibelt system):

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)

Observera att i det första exemplet kommer returvärdevariabeln rv att innehålla ett heltalsvärde; i det andra exemplet kommer den att innehålla ett bytes-objekt. Strukturlayouten för variabeln lockdata är systemberoende — därför kan det vara bättre att använda flock()-anropet.

Se även

Modul os

Om låsningsflaggorna O_SHLOCK och O_EXLOCK finns i modulen os (endast på BSD), är funktionen os.open() ett alternativ till funktionerna lockf() och flock().