View source for File descriptor

{{Short description|System resource identifier in operating systems}}
In [[Software:Unix|Unix]] and [[Unix-like]] computer operating systems, a '''file descriptor''' ('''FD''', less frequently '''fildes''') is a process-unique identifier ([[Handle (computing)|handle]]) for a file or other [[Input output|input/output]] [[System resource|resource]], such as a pipe or [[Network socket|network socket]]. 

File descriptors typically have non-negative [[Integer (computer science)|integer]] values, with negative values being reserved to indicate "no value" or error conditions.

File descriptors are a part of the [[POSIX]] [[Application programming interface|API]].  Each Unix [[Process (computing)|process]] (except perhaps daemons) should have three standard POSIX file descriptors, corresponding to the three [[Standard streams|standard streams]]:

{| class="wikitable"
!Integer value
!Name
!{{mono|&lt;[[Unistd.h|unistd.h]]&gt;}} symbolic constant<ref>{{cite web
 | url        = http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html
 | title      = The Open Group Base Specifications Issue 7, IEEE Std 1003.1-2008, 2016 Edition
 | author     = The Open Group
 | access-date = 2017-09-21
 }}</ref>
!{{mono|&lt;[[Stdio.h|stdio.h]]&gt;}} file stream<ref>{{cite web
 | url        = http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdio.h.html
 | id         = <stdio.h>
 | title      = The Open Group Base Specifications Issue 7, IEEE Std 1003.1-2008, 2016 Edition
 | author     = The Open Group
 | access-date = 2017-09-21
 }}</ref>
|-
|0
|Standard input
|{{mono|STDIN_FILENO}}
|{{mono|stdin}}
|-
|1
|Standard output
|{{mono|STDOUT_FILENO}}
|{{mono|stdout}}
|-
|2
|Standard error
|{{mono|STDERR_FILENO}}
|{{mono|stderr}}
|}

==Overview==
[[File:File table and inode table.svg|thumb|300px|File descriptors for a single process, file table and [[Inode|inode]] table. Note that multiple file descriptors can refer to the same file table entry (e.g., as a result of the [[Dup (system call)|dup]] system call{{r|bach}}{{rp|104}}) and that multiple file table entries can in turn refer to the same inode (if it has been opened multiple times; the table is still simplified because it represents inodes by file names, even though an inode can have [[Hard link|multiple names]]). File descriptor 3 does not refer to anything in the file table, signifying that it has been closed.]]
In the traditional implementation of Unix, file descriptors index into a per-process '''{{visible anchor|file descriptor table}}''' maintained by the kernel, that in turn indexes into a system-wide table of files opened by all processes, called the '''{{visible anchor|file table}}'''. This table records the ''mode'' with which the file (or other resource) has been opened: for reading, writing, appending, and possibly other modes.  It also indexes into a third table called the [[Inode|inode table]] that describes the actual underlying files.<ref name="bach">{{cite book
| title=The Design of the UNIX Operating System
| first=Maurice J.
| last=Bach
| year=1986
| edition=8
| publisher=Prentice-Hall
| pages=[https://archive.org/details/designofunixoper00bach/page/92 92–96]
| isbn=9780132017992
| url-access=registration
| url=https://archive.org/details/designofunixoper00bach/page/92
}}</ref>  To perform input or output, the process passes the file descriptor to the kernel through a [[System call|system call]], and the kernel will access the file on behalf of the process.  The process does not have direct access to the file or inode tables.

On [[Software:Linux|Linux]], the set of file descriptors open in a process can be accessed under the path <code>/proc/PID/fd/</code>, where PID is the [[Process identifier|process identifier]]. File descriptor <code>/proc/PID/fd/0</code> is <code>stdin</code>, <code>/proc/PID/fd/1</code> is <code>stdout</code>, and <code>/proc/PID/fd/2</code> is <code>stderr</code>. As a shortcut to these, any running process can also access ''its own'' file descriptors through the folders <code>/proc/self/fd</code> and <code>/dev/fd</code>.<ref>{{Cite web|url=https://unix.stackexchange.com/questions/676683/what-does-the-output-of-ll-proc-self-fd-from-ll-dev-fd-mean|title = Devices - What does the output of 'll /Proc/Self/Fd/' (From 'll /Dev/Fd') mean?}}</ref>

In [[Unix-like]] systems, file descriptors can refer to any Unix file type named in a file system. As well as regular files, this includes [[Directory (file systems)|directories]], block and character devices (also called "special files"), [[Unix domain socket]]s, and [[Named pipe|named pipe]]s. File descriptors can also refer to other objects that do not normally exist in the file system, such as [[Anonymous pipe|anonymous pipe]]s and [[Network socket|network socket]]s.

The FILE data structure in the C standard I/O library usually includes a low level file descriptor for the object in question on Unix-like systems. The overall data structure provides additional abstraction and is instead known as a ''file [[Handle (computing)|handle]].''

==Operations on file descriptors==
The following lists typical operations on file descriptors on modern [[Unix-like]] systems. Most of these functions are declared in the <code><unistd.h></code> header, but some are in the <code><fcntl.h></code> header instead.

===Creating file descriptors===
*{{mono|[[Open (system call)|open]]()}}
*{{mono|creat()}}<!-- Not a typo --><ref>{{cite web |url=http://pubs.opengroup.org/onlinepubs/9699919799/functions/creat.html |title=The Open Group Base Specifications Issue 7, IEEE Std 1003.1-2008, 2018 Edition – creat |author=The Open Group |access-date=2019-04-11 |}}</ref>
*{{mono|socket()}}
*{{mono|accept()}}
*{{mono|socketpair()}}
*{{mono|pipe()}}
*{{mono|epoll_create()}} (Linux)
*{{mono|signalfd()}} (Linux)
*{{mono|eventfd()}} (Linux)
*{{mono|timerfd_create()}} (Linux)
*{{mono|memfd_create()}} (Linux)
*{{mono|userfaultfd()}} (Linux)
*{{mono|fanotify_init()}} (Linux)
*{{mono|inotify_init()}} (Linux)
*{{mono|clone()}} (with flag CLONE_PIDFD, Linux)
*{{mono|pidfd_open()}} (Linux)
*{{mono|open_by_handle_at()}} (Linux)
*{{mono|kqueue()}} (BSD)
*{{mono|pdfork()}} (kFreeBSD)

===Deriving file descriptors===
*{{mono|dirfd()}}
*{{mono|fileno()}}

===Operations on a single file descriptor===
*{{mono|[[Read (system call)|read]](), [[Write (system call)|write]]()}}
*{{mono|readv()}}, {{mono|writev()}}
*{{mono|pread()}}, {{mono|pwrite()}}
*{{mono|recv()}}, {{mono|send()}}
*{{mono|recvfrom()}}, {{mono|sendto()}}
*{{mono|recvmsg()}}, {{mono|sendmsg()}} (also used for sending FDs to other processes over a Unix domain socket)
*{{mono|recvmmsg()}}, {{mono|sendmmsg()}}
*{{mono|lseek()}}, {{mono|llseek()}}
*{{mono|[[Stat (system call)|fstat()]]}}
*{{mono|fstatvfs()}}
*{{mono|fchmod()}}
*{{mono|fchown()}}
*{{mono|ftruncate()}}
*{{mono|fsync()}}
*{{mono|fdatasync()}}
*{{mono|fdopendir()}}
*{{mono|fgetxattr()}}, {{mono|fsetxattr()}} (Linux)
*{{mono|flistxattr()}}, {{mono|fremovexattr()}} (Linux)
*{{mono|statx}} (Linux)
*{{mono|setns}} (Linux)
*{{mono|vmsplice()}} (Linux)
*{{mono|pidfd_send_signal()}} (Linux)
*{{mono|pdkill()}} (kFreeBSD)
*{{mono|waitid()}} (with P_PIDFD ID type, Linux)
*{{mono|fdopen()}} (stdio function:converts file descriptor to FILE*)
*{{mono|dprintf()}} (stdio function: prints to file descriptor)

===Operations on multiple file descriptors===
*[[Select (Unix)|{{mono|select()}}]], {{mono|pselect()}}
*[[Poll (Unix)|{{mono|poll()}}]], {{mono|ppoll()}}
*{{mono|epoll_wait()}}, {{mono|epoll_pwait()}}, {{mono|epoll_pwait2()}} (Linux, takes a single epoll filedescriptor to wait on many other file descriptors)
*[[Epoll|{{mono|epoll ctl()}}]] (for Linux)
*[[Kqueue|{{mono|kqueue()}}]] (for BSD-based systems).
*{{mono|sendfile()}}
*[[Splice (system call)|{{mono|splice()}}]], {{mono|tee()}} (for Linux)
*{{mono|copy_file_range()}} (for Linux)

===Operations on the file descriptor table===
The {{mono|fcntl()}} function is used to perform various operations on a file descriptor, depending on the command argument passed to it. There are commands to get and set attributes associated with a file descriptor, including {{mono|F_GETFD, F_SETFD, F_GETFL}} and {{mono|F_SETFL}}.

*{{mono|[[Close (system call)|close()]]}}
*{{mono|closefrom()}} (BSD and Solaris only; deletes all file descriptors greater than or equal to specified number)
*{{mono|close_range()}} (for Linux)<ref>{{cite web |url=https://man7.org/linux/man-pages/man2/close_range.2.html |title=close_range(2) — Linux manual page |author=Stephen Kitt, Michael Kerrisk |access-date=2021-03-22 }}</ref>
*{{mono|[[Dup (system call)|dup()]]}} (duplicates an existing file descriptor guaranteeing to be the lowest number available file descriptor)
*{{mono|dup2()}}, {{mono|dup3()}} (Close fd1 if necessary, and make file descriptor fd1 point to the open file of fd2)
*{{mono|fcntl (F_DUPFD)}}

===Operations that modify process state===
*{{mono|fchdir()}} (sets the process's current working directory based on a directory file descriptor)
*{{mono|[[Mmap|mmap]]()}} (maps ranges of a file into the process's address space)

===File locking===
* {{mono|flock()}}
* {{mono|fcntl() (F_GETLK, F_SETLK}} and {{mono|F_SETLKW)}}
* {{mono|lockf()}}

===Sockets===
*{{mono|connect()}}
*{{mono|bind()}}
*{{mono|listen()}}
*{{mono|accept()}} (creates a new file descriptor for an incoming connection)
*{{mono|getsockname()}}
*{{mono|getpeername()}}
*{{mono|getsockopt()}}
*{{mono|setsockopt()}}
*{{mono|shutdown()}} (shuts down one or both halves of a full duplex connection)

===Miscellaneous===
*[[Ioctl|{{mono|ioctl()}}]] (a large collection of miscellaneous operations on a single file descriptor, often associated with a device)

==Upcoming operations==
A series of new operations on file descriptors has been added to many modern Unix-like systems, as well as numerous C libraries, to be standardized in a future version of [[POSIX]].<ref>{{cite book
  | title = Extended API Set, Part 2
  | publisher = The Open Group
  | date = October 2006
  | url = https://www2.opengroup.org/ogsys/catalog/c063
  | url-access = registration
  | isbn = 1931624674}}</ref> The <code>at</code> suffix signifies that the function takes an additional first argument supplying a file descriptor from which relative paths are resolved, the forms lacking the <code>at</code> suffix thus becoming equivalent to passing a file descriptor corresponding to the current working directory. The purpose of these new operations is to defend against a certain class of TOCTOU attacks.

*{{mono|openat()}}
*{{mono|faccessat()}}
*{{mono|fchmodat()}}
*{{mono|fchownat()}}
*{{mono|fstatat()}}
*{{mono|futimesat()}}
*{{mono|linkat()}}
*{{mono|mkdirat()}}
*{{mono|mknodat()}}
*{{mono|readlinkat()}}
*{{mono|renameat()}}
*{{mono|symlinkat()}}
*{{mono|unlinkat()}}
*{{mono|mkfifoat()}}
*{{mono|fdopendir()}}

==File descriptors as capabilities==
Unix file descriptors behave in many ways as [[Capability-based security|capabilities]].  They can be passed between processes across [[Unix domain socket]]s using the <code>sendmsg()</code> system call. Note, however, that what is actually passed is a reference to an "open file description" that has mutable state (the file offset, and the file status and access flags). This complicates the secure use of file descriptors as capabilities, since when programs share access to the same open file description, they can interfere with each other's use of it by changing its offset or whether it is blocking or non-blocking, for example.<ref>{{cite web
| url=http://www.eros-os.org/pipermail/cap-talk/2009-February/012137.html
| title=Building a bridge: library API's and file descriptors?
| first=Marcus
| last=Brinkmann
| date=2009-02-04
| work=cap-talk
| access-date=2017-09-21
| archive-url=https://archive.today/20120730163337/http://www.eros-os.org/pipermail/cap-talk/2009-February/012137.html
| archive-date=2012-07-30
| url-status=dead
}}</ref><ref>{{cite web
| url=http://jdebp.eu/FGA/dont-set-shared-file-descriptors-to-non-blocking-mode.html
| title=Don't set shared file descriptors to non-blocking I/O mode.
| first=Jonathan
| last=de Boyne Pollard
| year=2007
| access-date=2017-09-21}}</ref> In operating systems that are specifically designed as capability systems, there is very rarely any mutable state associated with a capability itself.

A Unix process' file descriptor table is an example of a [[C-list (computer security)|C-list]].

==See also==
* [[Software:Fuser (Unix)|fuser (Unix)]]
* [[Software:Lsof|lsof]]
* [[File Control Block]] (FCB) - an alternative scheme in CP/M and early versions of DOS

==References==
{{Reflist|30em}}

{{Object-capability security}}
{{Computer files}}

[[Category:POSIX]]
[[Category:Unix file system technology]]

de:Handle#Datei-Handle

{{Sourceattribution|File descriptor}}