Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 366 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3p/pthread_mutexattr_destroy.3p b/upstream/mageia-cauldron/man3p/pthread_mutexattr_destroy.3p
new file mode 100644
index 00000000..63177576
--- /dev/null
+++ b/upstream/mageia-cauldron/man3p/pthread_mutexattr_destroy.3p
@@ -0,0 +1,366 @@
+'\" et
+.TH PTHREAD_MUTEXATTR_DESTROY "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
+pthread_mutexattr_destroy,
+pthread_mutexattr_init
+\(em destroy and initialize the mutex attributes object
+.SH SYNOPSIS
+.LP
+.nf
+#include <pthread.h>
+.P
+int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP);
+int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIpthread_mutexattr_destroy\fR()
+function shall destroy a mutex attributes object; the object becomes,
+in effect, uninitialized. An implementation may cause
+\fIpthread_mutexattr_destroy\fR()
+to set the object referenced by
+.IR attr
+to an invalid value.
+.P
+A destroyed
+.IR attr
+attributes object can be reinitialized using
+\fIpthread_mutexattr_init\fR();
+the results of otherwise referencing the object after it
+has been destroyed are undefined.
+.P
+The
+\fIpthread_mutexattr_init\fR()
+function shall initialize a mutex attributes object
+.IR attr
+with the default value for all of the attributes defined by the
+implementation.
+.P
+Results are undefined if
+\fIpthread_mutexattr_init\fR()
+is called specifying an already initialized
+.IR attr
+attributes object.
+.P
+After a mutex attributes object has been used to initialize one or more
+mutexes, any function affecting the attributes object (including
+destruction) shall not affect any previously initialized mutexes.
+.P
+The behavior is undefined if the value specified by the
+.IR attr
+argument to
+\fIpthread_mutexattr_destroy\fR()
+does not refer to an initialized mutex attributes object.
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIpthread_mutexattr_destroy\fR()
+and
+\fIpthread_mutexattr_init\fR()
+shall return zero; otherwise, an error number shall be returned to
+indicate the error.
+.SH ERRORS
+The
+\fIpthread_mutexattr_init\fR()
+function shall fail if:
+.TP
+.BR ENOMEM
+Insufficient memory exists to initialize the mutex attributes object.
+.P
+These functions shall not return an error code of
+.BR [EINTR] .
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+If an implementation detects that the value specified by the
+.IR attr
+argument to
+\fIpthread_mutexattr_destroy\fR()
+does not refer to an initialized mutex attributes object, it is
+recommended that the function should fail and report an
+.BR [EINVAL] 
+error.
+.P
+See
+.IR "\fIpthread_attr_destroy\fR\^(\|)"
+for a general explanation of attributes. Attributes objects allow
+implementations to experiment with useful extensions and permit
+extension of this volume of POSIX.1\(hy2017 without changing the existing functions. Thus, they
+provide for future extensibility of this volume of POSIX.1\(hy2017 and reduce the temptation to
+standardize prematurely on semantics that are not yet widely
+implemented or understood.
+.P
+Examples of possible additional mutex attributes that have been
+discussed are
+.IR spin_only ,
+.IR limited_spin ,
+.IR no_spin ,
+.IR recursive ,
+and
+.IR metered .
+(To explain what the latter attributes might mean: recursive mutexes
+would allow for multiple re-locking by the current owner; metered
+mutexes would transparently keep records of queue length, wait time,
+and so on.) Since there is not yet wide agreement on the usefulness of
+these resulting from shared implementation and usage experience, they
+are not yet specified in this volume of POSIX.1\(hy2017. Mutex attributes objects,
+however, make it possible to test out these concepts for possible
+standardization at a later time.
+.SS "Mutex Attributes and Performance"
+.P
+Care has been taken to ensure that the default values of the mutex
+attributes have been defined such that mutexes initialized with the
+defaults have simple enough semantics so that the locking and unlocking
+can be done with the equivalent of a test-and-set instruction (plus
+possibly a few other basic instructions).
+.P
+There is at least one implementation method that can be used to reduce
+the cost of testing at lock-time if a mutex has non-default
+attributes. One such method that an implementation can employ (and
+this can be made fully transparent to fully conforming POSIX
+applications) is to secretly pre-lock any mutexes that are initialized
+to non-default attributes. Any later attempt to lock such a mutex
+causes the implementation to branch to the ``slow path'' as if the
+mutex were unavailable; then, on the slow path, the implementation can
+do the ``real work'' to lock a non-default mutex. The underlying
+unlock operation is more complicated since the implementation never
+really wants to release the pre-lock on this kind of mutex. This
+illustrates that, depending on the hardware, there may be certain
+optimizations that can be used so that whatever mutex attributes are
+considered ``most frequently used'' can be processed most efficiently.
+.SS "Process Shared Memory and Synchronization"
+.P
+The existence of memory mapping functions in this volume of POSIX.1\(hy2017 leads to the
+possibility that an application may allocate the synchronization
+objects from this section in memory that is accessed by multiple
+processes (and therefore, by threads of multiple processes).
+.P
+In order to permit such usage, while at the same time keeping the usual
+case (that is, usage within a single process) efficient, a
+.IR process-shared
+option has been defined.
+.P
+If an implementation supports the _POSIX_THREAD_PROCESS_SHARED
+option, then the
+.IR process-shared
+attribute can be used to indicate that mutexes or condition variables
+may be accessed by threads of multiple processes.
+.P
+The default setting of PTHREAD_PROCESS_PRIVATE
+has been chosen for the
+.IR process-shared
+attribute so that the most efficient forms of these synchronization
+objects are created by default.
+.P
+Synchronization variables that are initialized with the
+PTHREAD_PROCESS_PRIVATE
+.IR process-shared
+attribute may only be operated on by threads in the process that
+initialized them. Synchronization variables that are initialized with
+the PTHREAD_PROCESS_SHARED
+.IR process-shared
+attribute may be operated on by any thread in any process that has
+access to it. In particular, these processes may exist beyond the
+lifetime of the initializing process. For example, the following code
+implements a simple counting semaphore in a mapped file that may be
+used by many processes.
+.sp
+.RS 4
+.nf
+
+/* sem.h */
+struct semaphore {
+    pthread_mutex_t lock;
+    pthread_cond_t nonzero;
+    unsigned count;
+};
+typedef struct semaphore semaphore_t;
+.P
+semaphore_t *semaphore_create(char *semaphore_name);
+semaphore_t *semaphore_open(char *semaphore_name);
+void semaphore_post(semaphore_t *semap);
+void semaphore_wait(semaphore_t *semap);
+void semaphore_close(semaphore_t *semap);
+.P
+/* sem.c */
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/mman.h>
+#include <fcntl.h>
+#include <pthread.h>
+#include "sem.h"
+.P
+semaphore_t *
+semaphore_create(char *semaphore_name)
+{
+int fd;
+    semaphore_t *semap;
+    pthread_mutexattr_t psharedm;
+    pthread_condattr_t psharedc;
+.P
+    fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666);
+    if (fd < 0)
+        return (NULL);
+    (void) ftruncate(fd, sizeof(semaphore_t));
+    (void) pthread_mutexattr_init(&psharedm);
+    (void) pthread_mutexattr_setpshared(&psharedm,
+        PTHREAD_PROCESS_SHARED);
+    (void) pthread_condattr_init(&psharedc);
+    (void) pthread_condattr_setpshared(&psharedc,
+        PTHREAD_PROCESS_SHARED);
+    semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
+            PROT_READ | PROT_WRITE, MAP_SHARED,
+            fd, 0);
+    close (fd);
+    (void) pthread_mutex_init(&semap->lock, &psharedm);
+    (void) pthread_cond_init(&semap->nonzero, &psharedc);
+    semap->count = 0;
+    return (semap);
+}
+.P
+semaphore_t *
+semaphore_open(char *semaphore_name)
+{
+    int fd;
+    semaphore_t *semap;
+.P
+    fd = open(semaphore_name, O_RDWR, 0666);
+    if (fd < 0)
+        return (NULL);
+    semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
+            PROT_READ | PROT_WRITE, MAP_SHARED,
+            fd, 0);
+    close (fd);
+    return (semap);
+}
+.P
+void
+semaphore_post(semaphore_t *semap)
+{
+    pthread_mutex_lock(&semap->lock);
+    if (semap->count == 0)
+        pthread_cond_signal(&semapx->nonzero);
+    semap->count++;
+    pthread_mutex_unlock(&semap->lock);
+}
+.P
+void
+semaphore_wait(semaphore_t *semap)
+{
+    pthread_mutex_lock(&semap->lock);
+    while (semap->count == 0)
+        pthread_cond_wait(&semap->nonzero, &semap->lock);
+    semap->count--;
+    pthread_mutex_unlock(&semap->lock);
+}
+.P
+void
+semaphore_close(semaphore_t *semap)
+{
+    munmap((void *) semap, sizeof(semaphore_t));
+}
+.fi
+.P
+.RE
+.P
+The following code is for three separate processes that create, post,
+and wait on a semaphore in the file
+.BR /tmp/semaphore .
+Once the file is created, the post and wait programs increment and
+decrement the counting semaphore (waiting and waking as required) even
+though they did not initialize the semaphore.
+.sp
+.RS 4
+.nf
+
+/* create.c */
+#include "pthread.h"
+#include "sem.h"
+.P
+int
+main()
+{
+    semaphore_t *semap;
+.P
+    semap = semaphore_create("/tmp/semaphore");
+    if (semap == NULL)
+        exit(1);
+    semaphore_close(semap);
+    return (0);
+}
+.P
+/* post */
+#include "pthread.h"
+#include "sem.h"
+.P
+int
+main()
+{
+    semaphore_t *semap;
+.P
+    semap = semaphore_open("/tmp/semaphore");
+    if (semap == NULL)
+        exit(1);
+    semaphore_post(semap);
+    semaphore_close(semap);
+    return (0);
+}
+.P
+/* wait */
+#include "pthread.h"
+#include "sem.h"
+.P
+int
+main()
+{
+    semaphore_t *semap;
+.P
+    semap = semaphore_open("/tmp/semaphore");
+    if (semap == NULL)
+        exit(1);
+    semaphore_wait(semap);
+    semaphore_close(semap);
+    return (0);
+}
+.fi
+.P
+.RE
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.ad l
+.IR "\fIpthread_cond_destroy\fR\^(\|)",
+.IR "\fIpthread_create\fR\^(\|)",
+.IR "\fIpthread_mutex_destroy\fR\^(\|)"
+.ad b
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<pthread.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 .