CONFSTR(3P)

🌸 CONFSTR(3P) — the POSIX girlie's guide to get configurable variables 🌸

okay bestie, quick heads up before we dive in: this page is part of the POSIX Programmer's Manual 💖. The Linux implementation of this interface may differ (so pls go consult the corresponding Linux manual page for the deets on Linux behavior, fr), or honestly the interface might not even be implemented on Linux at all. 🙈 Just so you know what you're walking into.

---

✨ NAME ✨

confstr — get configurable variables 💅

---

🎀 SYNOPSIS 🎀

#include <unistd.h>

size_t confstr(int name, char *buf, size_t len);

like it's giving very "one function, three args, infinite power" energy 🔥

---

🦋 DESCRIPTION 🦋

So confstr() shall return configuration-defined string values. Its whole use and purpose is similar to sysconf(), except it's the one you call when you want string values instead of numeric ones. That's literally the difference. slay. ✨

The name argument represents the system variable you're querying. The implementation shall support the following name values, which are defined in <unistd.h>. It may support others too (mystery bonus names, iconic):

_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

look at that list. it ate. 👑

Now the actual behavior, bestie, listen up:

• If len is not 0, and if name has a configuration-defined value, confstr() shall copy that value into the len-byte buffer pointed to by buf.
• If the string to be returned is longer than len bytes, including the terminating null, then confstr() shall truncate the string to len-1 bytes and null-terminate the result. 😭
• The application can detect that the string was truncated by comparing the value returned by confstr() with len. iykyk.

If len is 0 and buf is a null pointer, then confstr() shall still return the integer value as defined below, but shall not return a string. So it's like, window shopping only, no purchase. 🛍️

🚨 If len is 0 but buf is not a null pointer, the result is unspecified. no cap. don't do that.

After a call to:

confstr(_CS_V7_ENV, buf, sizeof(buf))

the string stored in 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. very "here's the receipts" of env vars. 💖

If the implementation supports the POSIX shell option, the string stored in buf after a call to:

confstr(_CS_PATH, buf, sizeof(buf))

can be used as a value of the PATH environment variable that accesses all of the standard utilities of POSIX.1‐2008, that are provided in a manner accessible via the exec family of functions, if the return value is less than or equal to sizeof(buf). periodt. 🌈

---

💜 RETURN VALUE 💜

• If name has a configuration-defined value, confstr() 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 len, the string returned in buf is truncated. (so if the number it hands back is bigger than len, bestie, you got clipped ✂️)
• If name is invalid, confstr() shall return 0 and set errno to indicate the error. 🚩
• If name does not have a configuration-defined value, confstr() shall return 0 and leave errno unchanged. (subtle king behavior, does nothing and tells no one 💀)

---

🔥 ERRORS 🔥

The confstr() function shall fail if:

• EINVAL — The value of the name argument is invalid.

The following sections are informative. (aka, the fun bonus lore section, no rules just vibes 🌸)

---

🌟 EXAMPLES 🌟

None.

...literally nothing. iconic of it. 🎀

---

🫶 APPLICATION USAGE 🫶

An application can distinguish between an invalid name parameter value and one that corresponds to a configurable variable that has no configuration-defined value by checking if errno is modified. This mirrors the behavior of sysconf(). two peas in a pod fr fr. 🧚

The original need for this function was to provide a way of finding the configuration-defined default value for the environment variable PATH. Since 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‐2017, applications need a way to determine the system-supplied PATH environment variable value that contains the correct search path for the standard utilities. like, users will absolutely rearrange your whole filesystem vibe, and you need to know the real default. 💅

An application could use:

confstr(name, (char *)NULL, (size_t)0)

to find out how big a buffer is needed for the string value; use malloc() to allocate a buffer to hold the string; and call confstr() again to get the string. Alternately, it could allocate a fixed, static buffer that is big enough to hold most answers (perhaps 512 or 1024 bytes), but then use malloc() to allocate a larger buffer if it finds that this is too small. the classic "ask first, then buy" strategy. obsessed. ✨

---

🧠 RATIONALE 🧠

Application developers can normally determine any configuration variable by means of reading from the stream opened by a call to:

popen("command -p getconf variable", "r");

The confstr() function with a name argument of _CS_PATH returns a string that can be used as a PATH environment variable setting that will reference the standard shell and utilities as described in the Shell and Utilities volume of POSIX.1‐2017. 💫

The confstr() 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. no shared-static-buffer drama, no "wait whose pointer is this", just peace. 🕊️

---

🔮 FUTURE DIRECTIONS 🔮

None.

the future is... nothing. we stay present. 💜

---

👀 SEE ALSO 👀

• exec
• fpathconf()
• sysconf()

The Base Definitions volume of POSIX.1‐2017, <unistd.h>

The Shell and Utilities volume of POSIX.1‐2017, c99

---

📜 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 .

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 .

---

and that's the whole page bestie!! 💖✨🦋🌸 this one came to you courtesy of IEEE/The Open Group, dated 2017, from the CONFSTR(3P) page itself. go forth and query your configurable variables, you absolute icon. mwah. 💅👑