Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 236 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/fattach.3p b/upstream/archlinux/man3p/fattach.3p
new file mode 100644
index 00000000..f0b7c9ef
--- /dev/null
+++ b/upstream/archlinux/man3p/fattach.3p
@@ -0,0 +1,236 @@
+'\" et
+.TH FATTACH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+fattach
+\(em attach a STREAMS-based file descriptor to a file in the
+file system name space (\fBSTREAMS\fP)
+.SH SYNOPSIS
+.LP
+.nf
+#include <stropts.h>
+.P
+int fattach(int \fIfildes\fP, const char *\fIpath\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIfattach\fR()
+function shall attach a STREAMS-based file descriptor to a file,
+effectively associating a pathname with
+.IR fildes .
+The application shall ensure that the
+.IR fildes
+argument is a valid open file descriptor associated with a STREAMS
+file. The
+.IR path
+argument points to a pathname of an existing file. The application
+shall have appropriate privileges or be the owner of the file
+named by
+.IR path
+and have write permission. A successful call to
+\fIfattach\fR()
+shall cause all pathnames that name the file named by
+.IR path
+to name the STREAMS file associated with
+.IR fildes ,
+until the STREAMS file is detached from the file. A STREAMS file can be
+attached to more than one file and can have several pathnames
+associated with it.
+.P
+The attributes of the named STREAMS file shall be initialized as follows:
+the permissions, user ID, group ID, and times are set to those of the
+file named by
+.IR path ,
+the number of links is set to 1, and the size and device identifier are
+set to those of the STREAMS file associated with
+.IR fildes .
+If any attributes of the named STREAMS file are subsequently changed
+(for example, by
+\fIchmod\fR()),
+neither the attributes of the underlying file nor the attributes of the
+STREAMS file to which
+.IR fildes
+refers shall be affected.
+.P
+File descriptors referring to the underlying file, opened prior to an
+\fIfattach\fR()
+call, shall continue to refer to the underlying file.
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIfattach\fR()
+shall return 0. Otherwise, \-1 shall be returned and
+.IR errno
+set to indicate the error.
+.SH ERRORS
+The
+\fIfattach\fR()
+function shall fail if:
+.TP
+.BR EACCES
+Search permission is denied for a component of the path prefix, or the
+process is the owner of
+.IR path
+but does not have write permissions on the file named by
+.IR path .
+.TP
+.BR EBADF
+The
+.IR fildes
+argument is not a valid open file descriptor.
+.TP
+.BR EBUSY
+The file named by
+.IR path
+is currently a mount point or has a STREAMS file attached to it.
+.TP
+.BR ELOOP
+A loop exists in symbolic links encountered during resolution of the
+.IR path
+argument.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a component of a pathname is longer than
+{NAME_MAX}.
+.TP
+.BR ENOENT
+A component of
+.IR path
+does not name an existing file or
+.IR path
+is an empty string.
+.TP
+.BR ENOTDIR
+A component of the path prefix names an existing file that is neither
+a directory nor a symbolic link to a directory, or the
+.IR path
+argument contains at least one non-\c
+<slash>
+character and ends with one or more trailing
+<slash>
+characters.
+.TP
+.BR EPERM
+The effective user ID of the process is not the owner of the file named
+by
+.IR path
+and the process does not have appropriate privileges.
+.br
+.P
+The
+\fIfattach\fR()
+function may fail if:
+.TP
+.BR EINVAL
+The
+.IR fildes
+argument does not refer to a STREAMS file.
+.TP
+.BR ELOOP
+More than
+{SYMLOOP_MAX}
+symbolic links were encountered during resolution of the
+.IR path
+argument.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a pathname exceeds
+{PATH_MAX},
+or pathname resolution of a symbolic link produced an intermediate
+result with a length that exceeds
+{PATH_MAX}.
+.TP
+.BR EXDEV
+A link to a file on another file system was attempted.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Attaching a File Descriptor to a File"
+.P
+In the following example,
+.IR fd
+refers to an open STREAMS file. The call to
+\fIfattach\fR()
+associates this STREAM with the file
+.BR /tmp/named-STREAM ,
+such that any future calls to open
+.BR /tmp/named-STREAM ,
+prior to breaking the attachment via a call to
+\fIfdetach\fR(),
+will instead create a new file handle referring to the STREAMS file
+associated with
+.IR fd .
+.sp
+.RS 4
+.nf
+
+#include <stropts.h>
+\&...
+    int fd;
+    char *pathname = "/tmp/named-STREAM";
+    int ret;
+.P
+    ret = fattach(fd, pathname);
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+The
+\fIfattach\fR()
+function behaves similarly to the traditional
+\fImount\fR()
+function in the way a file is temporarily replaced by the root
+directory of the mounted file system. In the case of
+\fIfattach\fR(),
+the replaced file need not be a directory and the replacing file is a
+STREAMS file.
+.SH RATIONALE
+The file attributes of a file which has been the subject of an
+\fIfattach\fR()
+call are specifically set because of an artifact of the original
+implementation. The internal mechanism was the same as for the
+\fImount\fR()
+function. Since
+\fImount\fR()
+is typically only applied to directories, the effects when applied to
+a regular file are a little surprising, especially as regards the link
+count which rigidly remains one, even if there were several links
+originally and despite the fact that all original links refer to the
+STREAM as long as the
+\fIfattach\fR()
+remains in effect.
+.SH "FUTURE DIRECTIONS"
+The
+\fIfattach\fR()
+function may be removed in a future version.
+.SH "SEE ALSO"
+.IR "\fIfdetach\fR\^(\|)",
+.IR "\fIisastream\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<stropts.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .