1 files changed, 283 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/confstr.3p b/upstream/archlinux/man3p/confstr.3p
new file mode 100644
index 00000000..2ec41bde
--- /dev/null
+++ b/upstream/archlinux/man3p/confstr.3p
@@ -0,0 +1,283 @@
+'\" et
+.TH CONFSTR "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
+confstr
+\(em get configurable variables
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+.P
+size_t confstr(int \fIname\fP, char *\fIbuf\fP, size_t \fIlen\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIconfstr\fR()
+function shall return configuration-defined string values. Its use and
+purpose are similar to
+\fIsysconf\fR(),
+but it is used where string values rather than numeric values are
+returned.
+.P
+The
+.IR name
+argument represents the system variable to be queried. The
+implementation shall support the following name values, defined in
+.IR <unistd.h> .
+It may support others:
+.P
+.nf
+_CS_PATH
+_CS_POSIX_V7_ILP32_OFF32_CFLAGS
+_CS_POSIX_V7_ILP32_OFF32_LDFLAGS
+_CS_POSIX_V7_ILP32_OFF32_LIBS
+_CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
+_CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
+_CS_POSIX_V7_ILP32_OFFBIG_LIBS
+_CS_POSIX_V7_LP64_OFF64_CFLAGS
+_CS_POSIX_V7_LP64_OFF64_LDFLAGS
+_CS_POSIX_V7_LP64_OFF64_LIBS
+_CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
+_CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
+_CS_POSIX_V7_LPBIG_OFFBIG_LIBS
+_CS_POSIX_V7_THREADS_CFLAGS
+_CS_POSIX_V7_THREADS_LDFLAGS
+_CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
+_CS_V7_ENV
+_CS_POSIX_V6_ILP32_OFF32_CFLAGS
+_CS_POSIX_V6_ILP32_OFF32_LDFLAGS
+_CS_POSIX_V6_ILP32_OFF32_LIBS
+_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
+_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
+_CS_POSIX_V6_ILP32_OFFBIG_LIBS
+_CS_POSIX_V6_LP64_OFF64_CFLAGS
+_CS_POSIX_V6_LP64_OFF64_LDFLAGS
+_CS_POSIX_V6_LP64_OFF64_LIBS
+_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
+_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
+_CS_POSIX_V6_LPBIG_OFFBIG_LIBS
+_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
+_CS_V6_ENV
+.fi
+.P
+If
+.IR len
+is not 0, and if
+.IR name
+has a configuration-defined value,
+\fIconfstr\fR()
+shall copy that value into the
+.IR len -byte
+buffer pointed to by
+.IR buf .
+If the string to be returned is longer than
+.IR len
+bytes, including the terminating null, then
+\fIconfstr\fR()
+shall truncate the string to
+.IR len \-1
+bytes and null-terminate the result. The application can detect that
+the string was truncated by comparing the value returned by
+\fIconfstr\fR()
+with
+.IR len .
+.P
+If
+.IR len
+is 0 and
+.IR buf
+is a null pointer, then
+\fIconfstr\fR()
+shall still return the integer value as defined below, but shall not
+return a string. If
+.IR len
+is 0 but
+.IR buf
+is not a null pointer, the result is unspecified.
+.P
+After a call to:
+.sp
+.RS 4
+.nf
+
+confstr(_CS_V7_ENV, buf, sizeof(buf))
+.fi
+.P
+.RE
+.P
+the string stored in
+.IR buf
+shall contain a
+<space>-separated
+list of the variable=value environment variable pairs an
+implementation requires as part of specifying a conforming
+environment, as described in the implementations' conformance
+documentation.
+.P
+If the implementation supports the POSIX shell option, the string
+stored in
+.IR buf
+after a call to:
+.sp
+.RS 4
+.nf
+
+confstr(_CS_PATH, buf, sizeof(buf))
+.fi
+.P
+.RE
+.P
+can be used as a value of the
+.IR PATH
+environment variable that accesses all of the standard utilities of
+POSIX.1\(hy2008, that are provided in a manner accessible via the
+.IR exec
+family of functions, if the return value is less than or equal to
+.IR sizeof (\c
+.IR buf ).
+.SH "RETURN VALUE"
+If
+.IR name
+has a configuration-defined value,
+\fIconfstr\fR()
+shall return the size of buffer that would be needed to hold the entire
+configuration-defined value including the terminating null. If this
+return value is greater than
+.IR len ,
+the string returned in
+.IR buf
+is truncated.
+.P
+If
+.IR name
+is invalid,
+\fIconfstr\fR()
+shall return 0 and set
+.IR errno
+to indicate the error.
+.P
+If
+.IR name
+does not have a configuration-defined value,
+\fIconfstr\fR()
+shall return 0 and leave
+.IR errno
+unchanged.
+.SH ERRORS
+The
+\fIconfstr\fR()
+function shall fail if:
+.TP
+.BR EINVAL
+The value of the
+.IR name
+argument is invalid.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+An application can distinguish between an invalid
+.IR name
+parameter value and one that corresponds to a configurable variable
+that has no configuration-defined value by checking if
+.IR errno
+is modified. This mirrors the behavior of
+\fIsysconf\fR().
+.P
+The original need for this function was to provide a way of finding the
+configuration-defined default value for the environment variable
+.IR PATH .
+Since
+.IR PATH
+can be modified by the user to include directories that could contain
+utilities replacing the standard utilities in the Shell and Utilities volume of POSIX.1\(hy2017, applications
+need a way to determine the system-supplied
+.IR PATH
+environment variable value that contains the correct search path for
+the standard utilities.
+.P
+An application could use:
+.sp
+.RS 4
+.nf
+
+confstr(name, (char *)NULL, (size_t)0)
+.fi
+.P
+.RE
+.P
+to find out how big a buffer is needed for the string value; use
+\fImalloc\fR()
+to allocate a buffer to hold the string; and call
+\fIconfstr\fR()
+again to get the string. Alternately, it could allocate a fixed, static
+buffer that is big enough to hold most answers (perhaps 512 or 1\|024
+bytes), but then use
+\fImalloc\fR()
+to allocate a larger buffer if it finds that this is too small.
+.SH RATIONALE
+Application developers can normally determine any configuration
+variable by means of reading from the stream opened by a call to:
+.sp
+.RS 4
+.nf
+
+popen("command -p getconf variable", "r");
+.fi
+.P
+.RE
+.P
+The
+\fIconfstr\fR()
+function with a
+.IR name
+argument of _CS_PATH returns a string that can be used as a
+.IR PATH
+environment variable setting that will reference the standard shell and
+utilities as described in the Shell and Utilities volume of POSIX.1\(hy2017.
+.P
+The
+\fIconfstr\fR()
+function copies the returned string into a buffer supplied by the
+application instead of returning a pointer to a string. This allows a
+cleaner function in some implementations (such as those with
+lightweight threads) and resolves questions about when the application
+must copy the string returned.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIexec\fR\^",
+.IR "\fIfpathconf\fR\^(\|)",
+.IR "\fIsysconf\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<unistd.h>\fP"
+.P
+The Shell and Utilities volume of POSIX.1\(hy2017,
+.IR "\fIc99\fR\^"
+.\"
+.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 .