Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 298 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/sem_open.3p b/upstream/archlinux/man3p/sem_open.3p
new file mode 100644
index 00000000..aad38e9d
--- /dev/null
+++ b/upstream/archlinux/man3p/sem_open.3p
@@ -0,0 +1,298 @@
+'\" et
+.TH SEM_OPEN "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
+sem_open
+\(em initialize and open a named semaphore
+.SH SYNOPSIS
+.LP
+.nf
+#include <semaphore.h>
+.P
+sem_t *sem_open(const char *\fIname\fP, int \fIoflag\fP, ...);
+.fi
+.SH DESCRIPTION
+The
+\fIsem_open\fR()
+function shall establish a connection between a named semaphore
+and a process. Following a call to
+\fIsem_open\fR()
+with semaphore name
+.IR name ,
+the process may reference the semaphore associated with
+.IR name
+using the address returned from the call. This semaphore may be used
+in subsequent calls to
+\fIsem_wait\fR(),
+\fIsem_timedwait\fR(),
+\fIsem_trywait\fR(),
+\fIsem_post\fR(),
+and
+\fIsem_close\fR().
+The semaphore remains usable by this process until the semaphore is
+closed by a successful call to
+\fIsem_close\fR(),
+\fI_exit\fR(),
+or one of the
+.IR exec
+functions.
+.P
+The
+.IR oflag
+argument controls whether the semaphore is created or merely accessed
+by the call to
+\fIsem_open\fR().
+The following flag bits may be set in
+.IR oflag :
+.IP O_CREAT 10
+This flag is used to create a semaphore if it does not already exist.
+If O_CREAT is set and the semaphore already exists, then O_CREAT has no
+effect, except as noted under O_EXCL. Otherwise,
+\fIsem_open\fR()
+creates a named semaphore. The O_CREAT flag requires a third and a
+fourth argument:
+.IR mode ,
+which is of type
+.BR mode_t ,
+and
+.IR value ,
+which is of type
+.BR unsigned .
+The semaphore is created with an initial value of
+.IR value .
+Valid initial values for semaphores are less than or equal to
+{SEM_VALUE_MAX}.
+.RS 10 
+.P
+The user ID of the semaphore shall be set to the effective user ID of
+the process. The group ID of the semaphore shall be set to the effective
+group ID of the process; however, if the
+.IR name
+argument is visible in the file system, the group ID may be set to
+the group ID of the containing directory. The permission bits of the
+semaphore are set to the value of the
+.IR mode
+argument except those set in the file mode creation mask of the
+process. When bits in
+.IR mode
+other than the file permission bits are specified, the effect is
+unspecified.
+.P
+After the semaphore named
+.IR name
+has been created by
+\fIsem_open\fR()
+with the O_CREAT flag, other processes can connect to the semaphore by
+calling
+\fIsem_open\fR()
+with the same value of
+.IR name .
+.RE
+.IP O_EXCL 10
+If O_EXCL and O_CREAT are set,
+\fIsem_open\fR()
+fails if the semaphore
+.IR name
+exists. The check for the existence of the semaphore and the creation
+of the semaphore if it does not exist are atomic with respect to other
+processes executing
+\fIsem_open\fR()
+with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set,
+the effect is undefined.
+.RS 10 
+.P
+If flags other than O_CREAT and O_EXCL are specified in the
+.IR oflag
+parameter, the effect is unspecified.
+.RE
+.P
+The
+.IR name
+argument points to a string naming a semaphore object. It is
+unspecified whether the name appears in the file system and is visible
+to functions that take pathnames as arguments. The
+.IR name
+argument conforms to the construction rules for a pathname, except
+that the interpretation of
+<slash>
+characters other than the leading
+<slash>
+character in
+.IR name
+is implementation-defined, and that the length limits for the
+.IR name
+argument are implementation-defined and need not be the same as
+the pathname limits
+{PATH_MAX}
+and
+{NAME_MAX}.
+If
+.IR name
+begins with the
+<slash>
+character, then processes calling
+\fIsem_open\fR()
+with the same value of
+.IR name
+shall refer to the same semaphore object, as long as that name has not
+been removed. If
+.IR name
+does not begin with the
+<slash>
+character, the effect is implementation-defined.
+.P
+If a process makes multiple successful calls to
+\fIsem_open\fR()
+with the same value for
+.IR name ,
+the same semaphore address shall be returned for each such successful
+call, provided that there have been no calls to
+\fIsem_unlink\fR()
+for this semaphore, and at least one previous successful
+\fIsem_open\fR()
+call for this semaphore has not been matched with a
+\fIsem_close\fR()
+call.
+.P
+References to copies of the semaphore produce undefined results.
+.SH "RETURN VALUE"
+Upon successful completion, the
+\fIsem_open\fR()
+function shall return the address of the semaphore. Otherwise, it
+shall return a value of SEM_FAILED and set
+.IR errno
+to indicate the error. The symbol SEM_FAILED is defined in the
+.IR <semaphore.h> 
+header. No successful return from
+\fIsem_open\fR()
+shall return the value SEM_FAILED.
+.SH ERRORS
+If any of the following conditions occur, the
+\fIsem_open\fR()
+function shall return SEM_FAILED and set
+.IR errno
+to the corresponding value:
+.TP
+.BR EACCES
+The named semaphore exists and the permissions specified by
+.IR oflag
+are denied, or the named semaphore does not exist and permission to
+create the named semaphore is denied.
+.TP
+.BR EEXIST
+O_CREAT and O_EXCL are set and the named semaphore already exists.
+.TP
+.BR EINTR
+The
+\fIsem_open\fR()
+operation was interrupted by a signal.
+.TP
+.BR EINVAL
+The
+\fIsem_open\fR()
+operation is not supported for the given name, or O_CREAT was specified
+in
+.IR oflag
+and
+.IR value
+was greater than
+{SEM_VALUE_MAX}.
+.TP
+.BR EMFILE
+Too many semaphore descriptors or file descriptors are currently in use
+by this process.
+.TP
+.BR ENFILE
+Too many semaphores are currently open in the system.
+.TP
+.BR ENOENT
+O_CREAT is not set and the named semaphore does not exist.
+.TP
+.BR ENOMEM
+There is insufficient memory for the creation of the new named
+semaphore.
+.TP
+.BR ENOSPC
+There is insufficient space on a storage device for the creation of the
+new named semaphore.
+.P
+If any of the following conditions occur, the
+\fIsem_open\fR()
+function may return SEM_FAILED and set
+.IR errno
+to the corresponding value:
+.TP
+.BR ENAMETOOLONG
+.br
+The length of the
+.IR name
+argument exceeds
+{_POSIX_PATH_MAX}
+on systems that do not support the XSI option
+or exceeds
+{_XOPEN_PATH_MAX}
+on XSI systems,
+or has a pathname component that is longer than
+{_POSIX_NAME_MAX}
+on systems that do not support the XSI option
+or longer than
+{_XOPEN_NAME_MAX}
+on XSI systems.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+Early drafts required an error return value of \-1 with the type
+.BR "sem_t *"
+for the
+\fIsem_open\fR()
+function, which is not guaranteed to be portable across
+implementations. The revised text provides the symbolic error code
+SEM_FAILED to eliminate the type conflict.
+.SH "FUTURE DIRECTIONS"
+A future version might require the
+\fIsem_open\fR()
+and
+\fIsem_unlink\fR()
+functions to have semantics similar to normal file system operations.
+.SH "SEE ALSO"
+.ad l
+.IR "\fIsemctl\fR\^(\|)",
+.IR "\fIsemget\fR\^(\|)",
+.IR "\fIsemop\fR\^(\|)",
+.IR "\fIsem_close\fR\^(\|)",
+.IR "\fIsem_post\fR\^(\|)",
+.IR "\fIsem_timedwait\fR\^(\|)",
+.IR "\fIsem_trywait\fR\^(\|)",
+.IR "\fIsem_unlink\fR\^(\|)"
+.ad b
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<semaphore.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 .