STRCOLL(3POSIX)

🌸 STRCOLL — bestie, let's talk collating 🌸

okay so this is a page from the POSIX Programmer's Manual (yes, that manual, the fancy standards one 💅). Heads up tho: the Linux implementation of this interface might do its own thing, so if you're on Linux you should go peek at the matching Linux man page for the tea. Or, plot twist, the interface might just... not be implemented on Linux at all. 🙈

---

✨ NAME ✨

strcoll, strcoll_l — string comparison using collating information 🦋

---

✨ SYNOPSIS ✨

#include <string.h>

int strcoll(const char *s1, const char *s2);
int strcoll_l(const char *s1, const char *s2,
    locale_t locale);

---

✨ DESCRIPTION ✨

So for strcoll(): everything described on this page is aligned with the ISO C standard. If there's ever a conflict between what's written here and the ISO C standard, that was not intentional bestie, it's just an oopsie. This volume of POSIX.1‐2017 defers to the ISO C standard, periodt.

The strcoll() and strcoll_l() functions shall compare the string pointed to by s1 to the string pointed to by s2 — and both of those get interpreted as appropriate to the LC_COLLATE category of the current locale, or of the locale represented by locale, respectively. It's giving "who comes first in the alphabet, but make it locale-aware." 👑

The strcoll() and strcoll_l() functions shall not change the setting of errno if they're successful. Not touching it. Hands off. 🫶

And since no return value is reserved to indicate an error, if your app wants to check for error situations you gotta do the little ritual: set errno to 0, then call strcoll(), or strcoll_l(), and then check errno. That's the vibe check.

🚨 The behavior is undefined if the locale argument to strcoll_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle. Like, undefined undefined. Don't do it. 💀

---

✨ RETURN VALUE ✨

Upon successful completion, strcoll() shall return an integer that's greater than, equal to, or less than 0, according to whether the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 when both are interpreted as appropriate to the current locale. And on error, strcoll() may set errno, but no return value is reserved to indicate an error. So like, the return value isn't telling you "error," it's telling you "ordering." iykyk.

Upon successful completion, strcoll_l() shall return an integer greater than, equal to, or less than 0, according to whether the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 when both are interpreted as appropriate to the locale represented by locale. On error, strcoll_l() may set errno, but again — no return value is reserved to indicate an error. 🔥

---

✨ ERRORS ✨

These functions may fail if:

• EINVAL — the s1 or s2 arguments contain characters outside the domain of the collating sequence. 😭

The following sections are informative. (Translation: the actual requirements are done, everything after this is bonus content bestie.)

---

✨ EXAMPLES ✨

🌸 Comparing Nodes 🌸

The following example uses an application-defined function, node_compare(), to compare two nodes based on an alphabetical ordering of the string field. It's honestly so clean.

#include <string.h>
...
struct node { /* These are stored in the table. */
    char *string;
    int length;
};
...
int node_compare(const void *node1, const void *node2)
{
    return strcoll(((const struct node *)node1)->string,
        ((const struct node *)node2)->string);
}
...

---

✨ APPLICATION USAGE ✨

The strxfrm() and strcmp() functions should be used for sorting large lists. Yeah, strcoll() is cute for a one-off compare, but for big sorting situations you want the other girls. 👑

---

✨ RATIONALE ✨

None. (She said nothing. Iconic. 🤐)

---

✨ FUTURE DIRECTIONS ✨

None. (Same energy. Nothing to see here. ✨)

---

✨ SEE ALSO ✨

alphasort(), strcmp(), strxfrm()

The Base Definitions volume of POSIX.1‐2017, <string.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!! 💖 this one came from IEEE/The Open Group, 2017, filed under STRCOLL(3POSIX) — go forth and collate responsibly, no cap 🎀🦋✨