WCSXFRM(3POSIX)

💖 WCSXFRM(3POSIX) 💖

okay bestie, welcome to the POSIX Programmer's Manual, the iconic collection of pages that tells you how the Unix-y universe is supposed to behave. Quick vibe check before we start:

Heads up: this page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (so go peek at the corresponding Linux manual page for the real tea), or honestly the interface may not even be implemented on Linux at all. 🙈

---

✨ NAME ✨

wcsxfrm, wcsxfrm_l — wide-character string transformation. she transforms. that's the whole job. 💅

---

🌸 SYNOPSIS 🌸

#include <wchar.h>

size_t wcsxfrm(wchar_t *restrict ws1, const wchar_t *restrict ws2,
    size_t n);
size_t wcsxfrm_l(wchar_t *restrict ws1, const wchar_t *restrict ws2,
    size_t n, locale_t locale);

---

🦋 DESCRIPTION 🦋

So for wcsxfrm(): the functionality described on this reference page is aligned with the ISO C standard. If anything here fights with the ISO C standard, that conflict was not intentional, promise. This volume of POSIX.1‐2017 defers to the ISO C standard. periodt.

Here's the actual glow-up: wcsxfrm() and wcsxfrm_l() shall transform the wide-character string pointed to by ws2 and drop the resulting wide-character string into the array pointed to by ws1.

The transformation has to be built so that if you apply wcscmp() to two transformed wide strings, it returns a value greater than, equal to, or less than 0 — matching whatever wcscoll() and wcscoll_l() would have returned when applied to the same two original wide-character strings, using the same LC_COLLATE category of the current locale, or of the locale object locale, respectively. like, the transformed strings are the ✨sorted versions✨ of the originals' opinions.

No more than n wide-character codes shall be placed into the resulting array pointed to by ws1, including the terminating null wide-character code. And if n is 0, ws1 is permitted to be a null pointer (yes queen, go wild).

If copying takes place between objects that overlap, the behavior is undefined. don't do that. seriously. 💀

wcsxfrm() and wcsxfrm_l() shall not change the setting of errno if successful. not touching it. hands off.

Since no return value is reserved to indicate an error, if you're an application that wants to check for error situations, you gotta set errno to 0 first, then call wcsxfrm() or wcsxfrm_l(), then check errno. it's giving detective work 🔍.

The behavior is undefined if the locale argument to wcsxfrm_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle. fr fr, don't pass her a fake ID.

---

👑 RETURN VALUE 👑

wcsxfrm() and wcsxfrm_l() shall return the length of the transformed wide-character string, not including the terminating null wide-character code.

If the value returned is n or more, then the contents of the array pointed to by ws1 are unspecified. (so like... mystery box. don't count on it. 😭)

On error, wcsxfrm() and wcsxfrm_l() may set errno, but no return value is reserved to indicate an error.

---

🌈 ERRORS 🌈

These functions may fail if:

• EINVAL — the wide-character string pointed to by ws2 contains wide-character codes outside the domain of the collating sequence. she's out of range, bestie, she doesn't belong here. 🚫

The following sections are informative. (translation: cute bonus content, not the law 💕)

---

🎀 EXAMPLES 🎀

None.

literally nothing. we're serving an empty plate. 🍽️✨

---

🧚 APPLICATION USAGE 🧚

The transformation function is such that two transformed wide-character strings can be ordered by wcscmp() as appropriate to collating sequence information in the current locale (category LC_COLLATE). so like, transform first, compare second, slay third.

And the fact that when n is 0, ws1 is permitted to be a null pointer? super useful — it's how you figure out the size of the ws1 array before you actually do the transformation. measure twice, transform once, that's the vibe check. 📏

---

💜 RATIONALE 💜

None.

nothing to justify here, the girlies just get it. iykyk.

---

🔥 FUTURE DIRECTIONS 🔥

None.

the future is bright and also empty. ⭐

---

💫 SEE ALSO 💫

• wcscmp()
• wcscoll()

And from the Base Definitions volume of POSIX.1‐2017: <wchar.h> 🌸

---

📜 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!! brought to you by IEEE/The Open Group, 2017 — yeah, 2017, she's vintage, she's timeless, she's WCSXFRM(3POSIX) and she ATE. 💅✨🫶