XAddHost(3)

💅 XAddHost(3) — the Xlib host-access-control era 🎀

okay so this is one of those XLIB FUNCTIONS pages, bestie. welcome to the whole who's allowed to connect to my X server situation. it's giving gatekeeping, but make it networking ✨

---

🌸 NAME 🌸

XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XSetAccessControl, XEnableAccessControl, XDisableAccessControl, XHostAddress, XServerInterpretedAddress — literally the whole girlboss squad for controlling host access and the host control structure 🫶

---

✨ SYNTAX ✨

like, here's every single one of them, verbatim, no cap:

int XAddHost(Display *display, XHostAddress *host);

int XAddHosts(Display *display, XHostAddress *hosts, int num_hosts);

XHostAddress *XListHosts(Display *display, int *nhosts_return, Bool
       *state_return);

int XRemoveHost(Display *display, XHostAddress *host);

int XRemoveHosts(Display *display, XHostAddress *hosts, int num_hosts);

int XSetAccessControl(Display *display, int mode);

int XEnableAccessControl(Display *display);

int XDisableAccessControl(Display *display);

---

🦋 ARGUMENTS 🦋

• display — your connection to the X server. the main character of literally every Xlib call 💅
• host — the specific host getting added or removed. one (1) host, periodt.
• hosts — each host that's getting added or removed. like host but a whole group chat.
• mode — the mode, bestie. you can pass EnableAccess or DisableAccess. those are the only two vibes allowed here.
• nhosts_return — returns the number of hosts currently chillin' in the access control list 🎀
• num_hosts — specifies the number of hosts. yes, it's a count. yes, it matters.
• state_return — returns the state of the access control 🌈

---

💖 DESCRIPTION 💖

okay so buckle up, because there's like eight functions here and each one has lore.

🧚 XAddHost

XAddHost adds the specified host to the access control list for that display. the glow-up moment for a new machine ✨

but — the server must be on the same host as the client issuing the command, or a BadAccess error results. so like, no remote shenanigans, iykyk.

XAddHost can generate BadAccess and BadValue errors.

🧚 XAddHosts

XAddHosts adds each specified host to the access control list for that display. group project energy.

same rule though: the server must be on the same host as the client issuing the command, or a BadAccess error results.

XAddHosts can generate BadAccess and BadValue errors.

🧚 XListHosts

XListHosts returns the current access control list, plus whether the use of the list at connection setup was enabled or disabled. so it's literally the "who's on the list and are we even enforcing it" function 👑

XListHosts allows a program to find out what machines can make connections. it also returns a pointer to a list of host structures that were allocated by the function. when no longer needed, this memory should be freed by calling XFree — yes bestie, you have to free it, this is C, we don't do vibes-based memory management 😭

🧚 XRemoveHost

XRemoveHost removes the specified host from the access control list for that display.

the server must be on the same host as the client process, or a BadAccess error results.

⚠️ bestie this is the scary one: if you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server. you literally delete your own access. main character energy gone wrong 💀

XRemoveHost can generate BadAccess and BadValue errors.

🧚 XRemoveHosts

XRemoveHosts removes each specified host from the access control list for that display.

the X server must be on the same host as the client process, or a BadAccess error results.

⚠️ same warning, same drama: if you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed unless you reset the server. blocklist yourself at your own risk 🙈

XRemoveHosts can generate BadAccess and BadValue errors.

🧚 XSetAccessControl

XSetAccessControl either enables or disables the use of the access control list at each connection setup. one function, two moods.

XSetAccessControl can generate BadAccess and BadValue errors.

🧚 XEnableAccessControl

XEnableAccessControl enables the use of the access control list at each connection setup. it's the on switch 🔥

XEnableAccessControl can generate a BadAccess error.

🧚 XDisableAccessControl

XDisableAccessControl disables the use of the access control list at each connection setup. it's the off switch. (lowkey the chaotic option but okay 🌸)

XDisableAccessControl can generate a BadAccess error.

---

🎀 STRUCTURES 🎀

the XHostAddress struct

it contains:

typedef struct {
        int family;     /* for example FamilyInternet */
        int length;     /* length of address, in bytes */
        char *address;  /* pointer to where to find the address */
} XHostAddress;

so like, the run-down:

• the family member specifies which protocol address family to use (for example, TCP/IP or DECnet) and can be FamilyInternet, FamilyInternet6, FamilyServerInterpreted, FamilyDECnet, or FamilyChaos 🌈
• the length member specifies the length of the address in bytes.
• the address member specifies a pointer to the address.

the XServerInterpretedAddress struct

for the ServerInterpreted family, the length is ignored and the address member is a pointer to a XServerInterpretedAddress structure, which contains:

typedef struct {
        int typelength;         /* length of type string, in bytes */
        int valuelength;        /* length of value string, in bytes */
        char *type;             /* pointer to where to find the type string */
        char *value;            /* pointer to where to find the address */
} XServerInterpretedAddress;

the type and value members point to strings representing the type and value of the server interpreted entry.

⚠️ heads up: these strings may not be NULL-terminated, so care should be used when accessing them. fr fr, don't just printf these and pray 🙈

the typelength and valuelength members specify the length in bytes of the type and value strings. (the page says "in byte" but you know what she means 💅)

---

💀 DIAGNOSTICS 💀

• BadAccess — a client attempted to modify the access control list from other than the local (or otherwise authorized) host. like, read the room, you're not on the list.
• BadValue — some numeric value falls outside the range of values accepted by the request. unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. any argument defined as a set of alternatives can generate this error. so basically: numbers out here wildin' ✨

---

👑 SEE ALSO 👑

• XFree(3)
• Xlib - C Language X Interface

---

and that's the whole page, bestie 🫶 go forth and manage your host access list responsibly. this tea was served fresh from X Version 11, libX11 1.8.14, and the XAddHost(3) page itself — slay 💅✨