XpSetAttributes(3Xp)

💅 XpSetAttributes — the one where you set or update an attribute pool in a print context

okay so real talk, this is XpSetAttributes(3Xp), and it lives in the XPRINT FUNCTIONS family. If you're the kind of girlie who likes telling the X Print Server exactly what's what, this is your moment. 🎀

---

✨ SYNOPSIS ✨

cc [ flag... ] file... -lXp [ library... ]
#include <X11/extensions/Print.h>

void XpSetAttributes ( display, context, type, pool, replacement_rule )
      Display *display;
      XPContext context;
      XPAttributes type;
      char *pool;
      XPAttrReplacement replacement_rule;

---

🌸 ARGUMENTS 🌸

• display — a pointer to the Display structure, bestie. You get it back from XOpenDisplay. It's literally your whole connection to the X server.
• context — the print context whose attribute pool is about to get a glow-up (or a full replacement, we don't judge).
• type — specifies the attribute pool. Which pool? That's what this tells you.
• pool — an attribute pool represented as a resource string, encoded in COMPOUND_TEXT. Yes, encoded. Don't come at me with plain ASCII.
• replacement_rule — either XPAttrReplace or XPAttrMerge. Pick one, choose your fighter. ⚔️

---

💖 DESCRIPTION 💖

So XpSetAttributes takes pool — a COMPOUND_TEXT resource string stuffed with new name-value pairs — and shoves them into the attribute pool that type points at. The way it modifies things depends on replacement_rule:

• With XPAttrReplace, the existing attribute pool is discarded and replaced with pool. Gone. Done. New pool, who dis. 💀
• With XPAttrMerge, pool gets merged into the existing attribute pool: pre-existing name-value pairs are replaced, and non-existing name-value pairs are just added like they were always invited. 🫶

And important: the contents of pool are not affected by this call, so you can free it yourself afterwards. No sneaky ownership transfer, no cap.

---

Okay, now the part where the server gets opinions. 👑

When you set supported attribute names, the X Print Server and its associated driver will validate the new values and ignore the ones that are invalid — and when that happens, the previous values remain unchanged. So invalid input = nothing happens, not chaos.

When you set unsupported (that is, unknown) attribute names, no validation is done at all, and the name-value pairs will be set — even though they will not be used. It's giving "clutter in the group chat," but sure, go off. 💅

When you delete a supported attribute name — meaning you fail to reset it with XPAttrReplace — the X Print Server explicitly or implicitly resets the attribute to a default value. ✨

---

Also, heads up: when you set certain supported attributes, the X Print Server may modify other associated attributes as a side effect. The example they gave: considering the XPPrinterAttr attribute document-formats-supported, setting the XPDocAttr attribute document-format may cause a number of other attributes to change. Butterfly effect, but make it print server. 🦋

---

For attribute pools that are read-only (see "get only" in the XPAttributes definition), attempting to use XpSetAttributes generates a BadMatch. Rude? Maybe. Correct? Absolutely. For attribute pools that are writable, lists of the supported attributes can be found in the XPPrinterAttr pool.

The lifetime of all attribute pools is bounded by the lifetime of the print context they're contained in. When set, all attribute values will be retained across all Xp operations — until changed by the user directly, by the X Print Server directly, or changed because of a side effect when either the user or the X Print Server changed another attribute value.

Refer to a complete description of all print attributes, the precedence between print attributes, and the side effects of setting certain print attributes on other print attributes, etc. (Their words, not mine — go read the docs, bestie.)

---

Wanna monitor changes to the attribute pools? Look at XpSelectInput and the event XPAttributeNotify. Because a print context can be shared among clients, changes made by one client will be seen by all the others — and if selected for, the event XPAttributeNotify will be sent to all clients referencing the print context when changes do occur. So it is the responsibility of the clients sharing a print context to coordinate their operations. Communicate. Please. 😭

---

🧚 STRUCTURES 🧚

The values for the typedef XPAttributes in <X11/extensions/Print.h> are:

#define XPJobAttr        1    /∗ get/set */
#define XPDocAttr        2    /∗ get/set */
#define XPPageAttr       3    /∗ get/set - subset of XPDocAttr */
#define XPPrinterAttr    4    /∗ get only (library) */
#define XPServerAttr          5    /∗ get only (library), no context needed */

The values for the typedef XPAttrReplacement in <X11/extensions/Print.h> are:

#define XPAttrReplace    1
#define XPAttrMerge      2

---

🔥 DIAGNOSTICS 🔥

• BadAlloc — insufficient memory. You ran out. Skill issue, but recoverable.
• BadMatch — the attribute pool specified by pool cannot be set. Probably read-only, see above. 🙈
• BadValue — the value specified for type is not valid. Check your type, bestie.
• XPBadContext — the specified print context-id is not valid.
• XPBadSequence — a request to set an attribute pool occurred at a time when the attribute pool could not be modified. Their example: modifying XPJobAttr immediately after calling XpStartJob. Timing is everything, fr fr. ⭐

---

🍓 FILES 🍓

<X11/extensions/Print.h>

---

👑 SEE ALSO 👑

XpSelectInput(3Xp), XpStartJob(3Xp)

---

🌈 and that's the whole vibe. this iconic little page comes to you from X Version 11 and libXp 1.0.4 — mwah, slay, periodt. 💜