XrmUniqueQuark(3)

💜 XrmUniqueQuark — quarks, but make it a group chat

okay bestie so this is a page from the XLIB FUNCTIONS manual, and it's literally all about resource quarks — those tiny little integer-ish handles X uses to describe names, classes and representations. It's from the libX11 1.8.14 days of X Version 11, and ngl it's extremely useful, you just have to read it in the right voice. Here, I'll read it for you 🫶

---

✨ NAME ✨

XrmUniqueQuark, XrmStringToQuark, XrmPermStringToQuark, XrmQuarkToString, XrmStringToQuarkList, XrmStringToBindingQuarkList — these are the functions that manipulate resource quarks. That's the whole vibe of this page 💅

---

🌸 SYNOPSIS 🌸

First things first, you gotta pull in the header:

#include <X11/Xresource.h>

Then here's the one that makes a brand new one:

XrmQuark XrmUniqueQuark(void);

Then the string→quark glow-ups, and yes these macros are allll just aliases of the same function, iconique:

#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)

XrmQuark XrmStringToQuark(char *string);

XrmQuark XrmPermStringToQuark(_Xconst char *string);

💀 okay don't panic — the manpage literally repeats that exact block one more time, right here. I'm not messing with you, that's genuinely what's in the source. Copy-paste era, no cap. Here it is again because ✨fidelity✨:

#define XrmStringToName(string) XrmStringToQuark(string)
#define XrmStringToClass(string) XrmStringToQuark(string)
#define XrmStringToRepresentation(string) XrmStringToQuark(string)

XrmQuark XrmStringToQuark(char *string);

XrmQuark XrmPermStringToQuark(_Xconst char *string);

Then quark→string, the reverse slay:

#define XrmNameToString(name) XrmQuarkToString(name)
#define XrmClassToString(class) XrmQuarkToString(class)
#define XrmRepresentationToString(type) XrmQuarkToString(type)

char *XrmQuarkToString(XrmQuark quark);

Then the list-y ones, note how these macros wrap across lines in the original, I'm keeping it exactly as printed (yes, including that XrmStringToClassList(str,class) with no space — character for character, bestie 😌):

#define XrmStringToNameList(str, name)  XrmStringToQuarkList((str),
(name))
#define XrmStringToClassList(str,class) XrmStringToQuarkList((str),
(class))

void XrmStringToQuarkList(char *string, XrmQuarkList quarks_return);

void XrmStringToBindingQuarkList(_Xconst char *string, XrmBindingList
       bindings_return, XrmQuarkList quarks_return);

---

🎀 ARGUMENTS 🎀

• bindings_return — you hand this over and it comes back holding the binding list 🫶
• quark — the quark you're like "hey what's the string for this one" about
• quarks_return — comes back holding the list of quarks
• string — the string you want a quark (or a whole quark list) allocated for ✨

---

💖 DESCRIPTION 💖

🦋 the unique one 🦋

XrmUniqueQuark allocates a quark that is guaranteed not to represent any string that is known to the resource manager. That's it, that's the whole function. It's giving "I'm special and nobody knows me" main character energy 👑

🦋 string → quark 🦋

These functions can be used to convert from string to quark representation. Now, important caveat time: if the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent — so like, don't come for it if that happens, it's not defined behaviour, it's vibes 🫠

The string argument to XrmStringToQuark need not be permanently allocated storage. XrmPermStringToQuark is just like XrmStringToQuark, except that Xlib is permitted to assume the string argument is permanently allocated, and, hence, that it can be used as the value to be returned by XrmQuarkToString. So like, that's the trade: you promise it lives forever, it can hand that same pointer back to you 🔥

For any given quark, if XrmStringToQuark returns a non-NULL value, all future calls will return the same value (identical address). Consistency queen 🌈

🙈 and yeah — that whole string→quark paragraph is repeated verbatim in the original, twice total. So here it is again, faithfully, because I refuse to skip things:

These functions can be used to convert from string to quark representation. If the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent. The string argument to XrmStringToQuark need not be permanently allocated storage. XrmPermStringToQuark is just like XrmStringToQuark, except that Xlib is permitted to assume the string argument is permanently allocated, and, hence, that it can be used as the value to be returned by XrmQuarkToString.

For any given quark, if XrmStringToQuark returns a non-NULL value, all future calls will return the same value (identical address).

🦋 quark → string 🦋

These functions can be used to convert from quark representation to string. The string pointed to by the return value must not be modified or freed. Read that again bestie. Do not touch it. Do not free it. Hands off 🚫

The returned string is byte-for-byte equal to the original string passed to one of the string-to-quark routines. If no string exists for that quark, XrmQuarkToString returns NULL. And for any given quark, if XrmQuarkToString returns a non-NULL value, all future calls will return the same value (identical address) — same energy as before, it's consistent like that 💅

🦋 the quark list one 🦋

XrmStringToQuarkList converts the null-terminated string (generally a fully qualified name) to a list of quarks. The caller must allocate sufficient space for the quarks list before calling XrmStringToQuarkList. Not me forgetting to allocate, couldn't be me 😭

Note that the string must be in the valid ResourceName format (see section 15.1). And if the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent. Again. Same caveat. It's everywhere.

🦋 bindings, explained 🦋

A binding list is a list of type XrmBindingList and indicates if components of name or class lists are bound tightly or loosely (that is, if wildcarding of intermediate components is specified).

typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;

XrmBindTightly indicates that a period separates the components, and XrmBindLoosely indicates that an asterisk separates the components. Period = tight. Asterisk = loose. Got it? Got it 🎀

🦋 the binding quark list one 🦋

XrmStringToBindingQuarkList converts the specified string to a binding list and a quark list. The caller must allocate sufficient space for the quarks list and the binding list before calling XrmStringToBindingQuarkList — both of them, don't be out here allocating one and calling it a day 🙈

If the string is not in the Host Portable Character Encoding the conversion is implementation-dependent. (sir this is the fifth time—)

Component names in the list are separated by a period or an asterisk character. If the string does not start with period or asterisk, a period is assumed. For example, *a.b*c becomes:

quarks     a       b       c
bindings   loose   tight   loose

see, * loose, . tight, * loose — it literally ate and left no crumbs ✨

---

🦋 SEE ALSO 🦋

Go read these next, bestie, they're all connected:

• XrmGetResource(3)
• XrmInitialize(3)
• XrmMergeDatabases(3)
• XrmPutResource(3)

And of course, the big one: Xlib - C Language X Interface 📚

---

k bye ily, go forth and quark responsibly 🧚💖

this has been XrmUniqueQuark(3) from X Version 11, shipped with libX11 1.8.14 — mwah, take care of her 💜