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 Jul 11, 2023
  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 .It Cm rdlnk
  98 Treat
  99 .Nm
 100 vnodes as symbolic links consistently, in particular, follow
 101 the resolved name for the name lookups.
 102 This option is strictly stronger than the
 103 .Cm linrdlnk
 104 option, it changes not only the type returned by
 105 .Xr stat 2 ,
 106 but also causes the
 107 .Nm
 108 files to behave as symlinks.
 109 .El
 110 .Pp
 111 For
 112 .Nm
 113 mounted without the
 114 .Cm nodup
 115 mount option,
 116 if the file descriptor is open and the mode the file is being opened
 117 with is a subset of the mode of the existing descriptor, the call:
 118 .Bd -literal -offset indent
 119 fd = open("/dev/fd/0", mode);
 120 .Ed
 121 .Pp
 122 and the call:
 123 .Bd -literal -offset indent
 124 fd = fcntl(0, F_DUPFD, 0);
 125 .Ed
 126 .Pp
 127 are equivalent.
 128 Flags to the
 129 .Xr open 2
 130 call other than
 131 .Dv O_RDONLY ,
 132 .Dv O_WRONLY
 133 and
 134 .Dv O_RDWR
 135 are ignored.
 136 .Pp
 137 For
 138 .Nm
 139 mounted with the
 140 .Cm nodup
 141 option, and file descriptor referencing a vnode, the call:
 142 .Bd -literal -offset indent
 143 fd = open("/dev/fd/0", mode);
 144 .Ed
 145 .Pp
 146 reopens the referenced vnode with the specified
 147 .Fa mode .
 148 In other words, the
 149 .Fn open
 150 call above is equivalent to
 151 .Bd -literal -offset indent
 152 fd = openat(0, "", O_EMPTY_PATH, mode);
 153 .Ed
 154 .Pp
 155 In particular, if the file descriptor was opened with the
 156 .Dv O_PATH
 157 flag, then either
 158 .Dv O_EMPTY_PATH
 159 or
 160 .Fn open
 161 over
 162 .Nm
 163 mount with
 164 .Cm nodup
 165 option allows one to convert it to a regularly opened file,
 166 assuming that the current permissions allow the requested
 167 .Fa mode .
 168 .Pp
 169 .Em "Note:"
 170 .Pa /dev/fd/0 ,
 171 .Pa /dev/fd/1
 172 and
 173 .Pa /dev/fd/2
 174 files are created by default when devfs alone is mounted.
 175 .Nm
 176 creates entries for all file descriptors opened by the process.
 177 .Sh FILES
 178 .Bl -tag -width /dev/stderr -compact
 179 .It Pa /dev/fd/#
 180 .El
 181 .Sh EXAMPLES
 182 To mount a
 183 .Nm
 184 volume located on
 185 .Pa /dev/fd :
 186 .Pp
 187 .Dl "mount -t fdescfs none /dev/fd"
 188 .Pp
 189 For
 190 .Xr linux 4
 191 ABI compatibility:
 192 .Pp
 193 .Dl "mount -t fdescfs -o linrdlnk none /compat/linux/dev/fd"
 194 .Pp
 195 For substitute of
 196 .Dv O_EMPTY_PATH
 197 flag use:
 198 .Pp
 199 .Dl "mount -t fdescfs -o nodup none /dev/fdpath"
 200 .Sh SEE ALSO
 201 .Xr devfs 5 ,
 202 .Xr mount 8
 203 .Sh HISTORY
 204 The
 205 .Nm
 206 file system first appeared in
 207 .Bx 4.4 .
 208 The
 209 .Nm
 210 manual page first appeared in
 211 .Fx 2.2 .
 212 .Sh AUTHORS
 213 .An -nosplit
 214 The
 215 .Nm
 216 manual page was written by
 217 .An Mike Pritchard Aq Mt mpp@FreeBSD.org ,
 218 and was based on the
 219 manual page written by
 220 .An Jan-Simon Pendry .