share/man/man5/fdescfs.5

   1 .\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
   2 .\"
   3 .\" Copyright (c) 1996
   4 .\"     Mike Pritchard <mpp@FreeBSD.org>.  All rights reserved.
   5 .\"
   6 .\" Copyright (c) 1992, 1993, 1994
   7 .\"     The Regents of the University of California.  All rights reserved.
   8 .\" All rights reserved.
   9 .\"
  10 .\" This code is derived from software donated to Berkeley by
  11 .\" Jan-Simon Pendry.
  12 .\"
  13 .\" Parts of this documentation was written by
  14 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
  15 .\" from the FreeBSD Foundation.
  16 .\"
  17 .\" Redistribution and use in source and binary forms, with or without
  18 .\" modification, are permitted provided that the following conditions
  19 .\" are met:
  20 .\" 1. Redistributions of source code must retain the above copyright
  21 .\"    notice, this list of conditions and the following disclaimer.
  22 .\" 2. Redistributions in binary form must reproduce the above copyright
  23 .\"    notice, this list of conditions and the following disclaimer in the
  24 .\"    documentation and/or other materials provided with the distribution.
  25 .\" 3. Neither the name of the University nor the names of its contributors
  26 .\"    may be used to endorse or promote products derived from this software
  27 .\"    without specific prior written permission.
  28 .\"
  29 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  30 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  31 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  32 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  33 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  34 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  35 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  36 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  37 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  38 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  39 .\" SUCH DAMAGE.
  40 .\"
  41 .\" $FreeBSD$
  42 .\"
  43 .Dd May 17, 2021
  44 .Dt FDESCFS 5
  45 .Os
  46 .Sh NAME
  47 .Nm fdescfs
  48 .Nd file-descriptor file system
  49 .Sh SYNOPSIS
  50 .Bd -literal
  51 fdescfs /dev/fd fdescfs rw 0 0
  52 .Ed
  53 .Sh DESCRIPTION
  54 The file-descriptor file system, or
  55 .Nm ,
  56 provides access to the per-process file descriptor
  57 namespace in the global file system namespace.
  58 The conventional mount point is
  59 .Pa /dev/fd .
  60 .Pp
  61 The file system's contents
  62 appear as a list of numbered files
  63 which correspond to the open files of the process reading the
  64 directory.
  65 The files
  66 .Pa /dev/fd/0
  67 through
  68 .Pa /dev/fd/#
  69 refer to file descriptors which can be accessed through the file
  70 system.
  71 .Pp
  72 The following mount options can be used when mounting
  73 .Nm
  74 filesystem:
  75 .Bl -tag -width linrdlnk
  76 .It Cm nodup
  77 For file descriptors referencing vnodes, instead of the
  78 .Xr dup 2
  79 semantic described above, implement re-opening of the referenced vnode.
  80 See below for more details.
  81 .It Cm linrdlnk
  82 Report the type of the
  83 .Nm
  84 vnode as
  85 .Dv VLNK
  86 instead of
  87 .Fx
  88 traditional
  89 .Dv VCHR .
  90 For
  91 .Xr linux 4
  92 ABI compatibility mount
  93 .Nm
  94 volume with the
  95 .Cm linrdlnk
  96 option.
  97 .El
  98 .Pp
  99 For
 100 .Nm
 101 mounted without the
 102 .Cm nodup
 103 mount option,
 104 if the file descriptor is open and the mode the file is being opened
 105 with is a subset of the mode of the existing descriptor, the call:
 106 .Bd -literal -offset indent
 107 fd = open("/dev/fd/0", mode);
 108 .Ed
 109 .Pp
 110 and the call:
 111 .Bd -literal -offset indent
 112 fd = fcntl(0, F_DUPFD, 0);
 113 .Ed
 114 .Pp
 115 are equivalent.
 116 Flags to the
 117 .Xr open 2
 118 call other than
 119 .Dv O_RDONLY ,
 120 .Dv O_WRONLY
 121 and
 122 .Dv O_RDWR
 123 are ignored.
 124 .Pp
 125 For
 126 .Nm
 127 mounted with the
 128 .Cm nodup
 129 option, and file descriptor referencing a vnode, the call:
 130 .Bd -literal -offset indent
 131 fd = open("/dev/fd/0", mode);
 132 .Ed
 133 .Pp
 134 reopens the referenced vnode with the specified
 135 .Fa mode .
 136 In other words, the
 137 .Fn open
 138 call above is equivalent to
 139 .Bd -literal -offset indent
 140 fd = openat(0, "", O_EMPTY_PATH, mode);
 141 .Ed
 142 .Pp
 143 In particular, if the file descriptor was opened with the
 144 .Dv O_PATH
 145 flag, then either
 146 .Dv O_EMPTY_PATH
 147 or
 148 .Fn open
 149 over
 150 .Nm
 151 mount with
 152 .Cm nodup
 153 option allows one to convert it to a regularly opened file,
 154 assuming that the current permissions allow the requested
 155 .Fa mode .
 156 .Pp
 157 .Em "Note:"
 158 .Pa /dev/fd/0 ,
 159 .Pa /dev/fd/1
 160 and
 161 .Pa /dev/fd/2
 162 files are created by default when devfs alone is mounted.
 163 .Nm
 164 creates entries for all file descriptors opened by the process.
 165 .Sh FILES
 166 .Bl -tag -width /dev/stderr -compact
 167 .It Pa /dev/fd/#
 168 .El
 169 .Sh EXAMPLES
 170 To mount a
 171 .Nm
 172 volume located on
 173 .Pa /dev/fd :
 174 .Pp
 175 .Dl "mount -t fdescfs none /dev/fd"
 176 .Pp
 177 For
 178 .Xr linux 4
 179 ABI compatibility:
 180 .Pp
 181 .Dl "mount -t fdescfs -o linrdlnk none /compat/linux/dev/fd"
 182 .Pp
 183 For substitute of
 184 .Dv O_EMPTY_PATH
 185 flag use:
 186 .Pp
 187 .Dl "mount -t fdescfs -o nodup none /dev/fdpath"
 188 .Sh SEE ALSO
 189 .Xr devfs 5 ,
 190 .Xr mount 8
 191 .Sh HISTORY
 192 The
 193 .Nm
 194 file system first appeared in
 195 .Bx 4.4 .
 196 The
 197 .Nm
 198 manual page first appeared in
 199 .Fx 2.2 .
 200 .Sh AUTHORS
 201 .An -nosplit
 202 The
 203 .Nm
 204 manual page was written by
 205 .An Mike Pritchard Aq Mt mpp@FreeBSD.org ,
 206 and was based on the
 207 manual page written by
 208 .An Jan-Simon Pendry .