XCURSOR(3)

💖 XCURSOR(3) 💖 — X Version 11, the cursor management era

okay bestie, sit down, hydrate, because we're about to talk about cursors and honestly? it's giving main character energy. this is the Xcursor library, and it is exactly what it sounds like. let's go 🦋

---

🌸 NAME 🌸

• Xcursor — cursor management library. that's the whole job. she manages cursors. iconic behavior, no notes 💅

---

✨ SYNOPSIS ✨

#include <X11/Xcursor/Xcursor.h>

like, that's the include. that's it. put it in your file and suddenly you have cursor powers 🫶

---

🎀 DESCRIPTION 🎀

Xcursor is a simple library designed to help you locate and load cursors. fr fr, that's the mission statement.

here's the tea:

• cursors can be loaded from files or from memory — your choice, your vibe
• there's a whole library of common cursors that map to the standard X cursor names (iykyk)
• cursors can exist in several sizes, and the library will automatically pick the best size for you. she's thoughtful like that. queen behavior 👑

---

🌈 FUNCTIONAL OVERVIEW 🌈

so Xcursor is built in a couple of layers, like a little parfait of functionality 🍨

• bottom layer: the code that can load cursor images from files. the ground floor. the foundation. the bedrock, bestie.
• above that: a layer that locates cursor files based on the library path and theme. she's out here doing detective work 🔍
• at the top: a layer that builds cursors either out of an image loaded from a file, or one of the standard X cursors.

and here's a very important detail, so listen up: when you're using images loaded from files, Xcursor prefers to use the Render extension CreateCursor request if it's supported by the X server. where that's not supported, Xcursor maps the cursor image to a standard X cursor and uses the core CreateCursor request instead. she adapts. she's flexible. we love a resourceful icon 💅

---

🗂️ CURSOR FILES 🗂️

Xcursor defines a new format for cursors on disk. and when I say new I mean she said "I'll make my own format, with blackjack and—" anyway:

• each file holds one or more cursor images
• each cursor image is tagged with a nominal size so the best size can be selected automatically
• multiple cursors of the same nominal size can be loaded together; applications are expected to use them as an animated sequence 🎞️

Cursor files are stored as a header containing a table of contents followed by a sequence of chunks. The table of contents indicates the type, subtype and position in the file of each chunk. The file header looks like:

magic:    CARD32 "Xcur" (0x58, 0x63, 0x75, 0x72)
header:   CARD32 bytes in this header
version:  CARD32 file version number
ntoc:     CARD32 number of toc entries
toc:      LISTofTOC table of contents

Each table of contents entry looks like:

type:     CARD32 entry type
subtype:  CARD32 type-specific label - size for images
position: CARD32 absolute byte position of table in file

Each chunk in the file has set of common header fields followed by additional type-specific fields:

header:   CARD32 bytes in chunk header (including type-specific fields)
type:     CARD32 must match type in TOC for this chunk
subtype:  CARD32 must match subtype in TOC for this chunk
version:  CARD32 version number for this chunk type

There are currently two chunk types defined for cursor files: comments and images. Comments look like:

header:   20 Comment headers are 20 bytes
type:     0xfffe0001 Comment type is 0xfffe0001
subtype:  { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) }
version:  1
length:   CARD32 byte length of UTF-8 string
string:   LISTofCARD8 UTF-8 string

Images look like:

header:   36 Image headers are 36 bytes
type:     0xfffd0002 Image type is 0xfffd0002
subtype:  CARD32 Image subtype is the nominal size
version:  1
width:    CARD32 Must be less than or equal to 0x7fff
height:   CARD32 Must be less than or equal to 0x7fff
xhot:     CARD32 Must be less than or equal to width
yhot:     CARD32 Must be less than or equal to height
delay:    CARD32 Delay between animation frames in milliseconds
pixels:   LISTofCARD32 Packed ARGB format pixels

---

🎨 THEMES 🎨

Xcursor (mostly) follows the freedesktop.org spec for theming icons. mostly. she's doing her best okay 😭

The default search path it uses is

~/.local/share/icons, ~/.icons, /usr/share/icons, /usr/share/pixmaps

Within each of these directories, it searches for a directory using the theme name:

• Within the theme directory, it looks for cursor files in the “cursors” subdirectory.

Xcursor looks for a specific file, which must be one of the cursor shape names, e.g., as used in XcursorLibraryLoadImage or XcursorLibraryShape.

• If it finds no matching cursor file in the “cursors” subdirectory, Xcursor next looks for an “index.theme” file in each theme directory to look for inherited themes. Those are lines in this format:

Inherits = theme-name

Xcursor uses the first inherited theme-name, ignoring others which may exist in a given “index.theme” file. If it finds an inherited theme, Xcursor searches along the path to use that as well. Xcursor ignores other keys in the “index.theme” file, including “Name” (i.e., the name which a graphical application may use as the presentation name).

More than one theme-name may be listed on the Inherits= line. The freedesktop.org spec states that list items are separated by commas. Xcursor also accepts semicolon, but translates both to colon when searching the path. Xcursor expects only one Inherits= line; the freedesktop.org spec is unclear whether multiple keys are allowed. 💀

If no theme is set, or if no cursor is found for the specified theme anywhere along the path, Xcursor checks the “default” theme.

🫶 When Xcursor finds a cursor file, it stops searching. It always uses the first cursor file found while searching along the path. first come, first served, periodt.

---

🧬 DATATYPES 🧬

XcursorImage

holds a single cursor image in memory. Each pixel in the cursor is a 32-bit value containing ARGB with A in the high byte.

typedef struct _XcursorImage {
    XcursorDim           size;    /* nominal size for matching */
    XcursorDim           width;   /* actual width */
    XcursorDim           height;  /* actual height */
    XcursorDim           xhot;    /* hot spot x (must be inside image) */
    XcursorDim           yhot;    /* hot spot y (must be inside image) */
    XcursorPixel        *pixels;  /* pointer to pixels */
} XcursorImage;

XcursorImages

holds multiple XcursorImage structures. They are all freed when the XcursorImages is freed in XcursorImagesDestroy.

typedef struct _XcursorImages {
    int                  nimage;  /* number of images */
    XcursorImage        **images; /* array of XcursorImage pointers */
} XcursorImages;

XcursorCursors

Holds multiple Cursor objects. They are all freed when the XcursorCursors is freed. These are reference counted so that multiple XcursorAnimate structures can use the same XcursorCursors. sharing is caring ✨

typedef struct _XcursorCursors {
    Display             *dpy;     /* Display holding cursors */
    int                  ref;     /* reference count */
    int                  ncursor; /* number of cursors */
    Cursor              *cursors; /* array of cursors */
} XcursorCursors;

XcursorAnimate

References a set of cursors and a sequence within that set. Multiple XcursorAnimate structures may reference the same XcursorCursors; each holds a reference which is removed when the XcursorAnimate is freed.

typedef struct _XcursorAnimate {
    XcursorCursors      *cursors; /* list of cursors to use */
    int                  sequence; /* which cursor is next */
} XcursorAnimate;

XcursorFile

Xcursor provides an abstract API for accessing the file data. Xcursor provides a stdio implementation of this abstract API; applications are free to create additional implementations. These functions parallel the stdio functions in return value and expected argument values; the read and write functions flip the arguments around to match the POSIX versions. sneaky little switcheroo 🙈

typedef struct _XcursorFile {
    void *closure;
    int (*read)  (XcursorFile *file, unsigned char *buf, int len);
    int (*write) (XcursorFile *file, unsigned char *buf, int len);
    int (*seek)  (XcursorFile *file, long offset, int whence);
};

---

🔧 FUNCTIONS 🔧

🫧 Object Management 🫧

XcursorImage *XcursorImageCreate (
               int                    width,
               int                    height)

void XcursorImageDestroy (
               XcursorImage          *image)

Allocate and free images. On allocation, the hotspot and the pixels are left uninitialized (so like, don't trust them, they're not ready yet 😭). The size is set to the maximum of width and height.

XcursorImages *XcursorImagesCreate (
               int                    size)

void XcursorImagesDestroy (
               XcursorImages         *images)

Allocate and free arrays to hold multiple cursor images. On allocation, nimage is set to zero.

XcursorCursors *XcursorCursorsCreate (
               Display               *dpy,
               int                    size)

void XcursorCursorsDestroy (
               XcursorCursors        *cursors)

Allocate and free arrays to hold multiple cursors. On allocation, ncursor is set to zero, ref is set to one. starting fresh, bestie 🧚

---

📖 Reading and writing images 📖

XcursorImage *XcursorXcFileLoadImage (
               XcursorFile           *file,
               int                    size)

XcursorImages *XcursorXcFileLoadImages (
               XcursorFile           *file,
               int                    size)

XcursorImages *XcursorXcFileLoadAllImages (
               XcursorFile           *file)

XcursorBool XcursorXcFileLoad (
               XcursorFile           *file,
               XcursorComments       **commentsp,
               XcursorImages         **imagesp)

XcursorBool XcursorXcFileSave (
               XcursorFile           *file,
               const XcursorComments *comments,
               const XcursorImages   *images)

These read and write cursors from an XcursorFile handle. After reading, the file pointer will be left at some random place in the file. not kidding, it just... wanders off. she does what she wants 💀

XcursorImage *XcursorFileLoadImage (
               FILE                  *file,
               int                    size)

XcursorImages *XcursorFileLoadImages (
               FILE                  *file,
               int                    size)

XcursorImages *XcursorFileLoadAllImages (
               FILE                  *file)

XcursorBool XcursorFileLoad (
               FILE                  *file,
               XcursorComments       **commentsp,
               XcursorImages         **imagesp)

XcursorBool XcursorFileSaveImages (
               FILE                  *file,
               const XcursorImages   *images)

XcursorBool XcursorFileSave (
               FILE                  *file,
               const XcursorComments *comments,
               const XcursorImages   *images)

These ones read and write cursors from a stdio FILE handle. 💖 And writing flushes before it returns, so any errors should get caught — no sneaky silent fails, we love accountability.

XcursorImage *XcursorFilenameLoadImage (
               const char            *filename,
               int                    size)

XcursorImages *XcursorFilenameLoadImages (
               const char            *filename,
               int                    size)

XcursorImages *XcursorFilenameLoadAllImages (
               const char            *file)

XcursorBool XcursorFilenameLoad (
               const char            *file,
               XcursorComments       **commentsp,
               XcursorImages         **imagesp)

XcursorBool XcursorFilenameSaveImages (
               const char            *filename,
               const XcursorImages   *images)

XcursorBool XcursorFilenameSave (
               const char            *file,
               const XcursorComments *comments,
               const XcursorImages   *images)

These are literally the same energy as the stdio FILE interfaces above, bestie — they just take filenames instead. Same vibes, different entry point. 🦋

---

🌸 Reading library images 🌸

XcursorImage *XcursorLibraryLoadImage (
               const char            *name,
               const char            *theme,
               int                    size)

XcursorImages *XcursorLibraryLoadImages (
               const char            *name,
               const char            *theme,
               int                    size)

Okay so these ones go searching through the library path, and they load the first file they find at the size you asked for. They use a private little helper function (XcursorScanTheme) to suss out the right theme, and here's the tea:

• If theme is not NULL, use that. simple as.
• If theme is NULL, or there was no match for the theme you wanted, then use "default" as the theme name. slay, we have a fallback. 💅
• If neither search works out? These functions return NULL. no cursor for you, babe. 😭

And the two functions differ by more than just how many images get loaded, iykyk:

• XcursorLibraryLoadImage calls XcursorFileLoadImage, but
• XcursorLibraryLoadImages calls XcursorFileLoadImages, and (on success) it calls XcursorImagesSetName to associate name with the result. ✨

---

💜 Library attributes 💜

const char * XcursorLibraryPath (void)

Returns the library search path, and the logic is giving very straightforward:

• If the environment variable XCURSOR_PATH is set, return that value. periodt.
• Otherwise, return the compiled-in search path.

int XcursorLibraryShape (
               const char            *library)

Searches Xcursor's table of cursor font names for the given "shape name" (library):

• If found, it returns the index into that table, multiplied by two (to account for the source- and mask-values used in an X cursor font). math girlies rise 🧮
• If not found, it returns -1. 💀

---

🎀 Cursor APIs 🎀

Cursor XcursorFilenameLoadCursor (
               Display               *dpy,
               const char            *file)

XcursorCursors *XcursorFilenameLoadCursors (
               Display               *dpy,
               const char            *file)

These load cursors from the file you specified. 📁

Cursor XcursorLibraryLoadCursor (
               Display               *dpy,
               const char            *name)

XcursorCursors *XcursorLibraryLoadCursors (
               Display               *dpy,
               const char            *name)

These load cursors using the library name you gave them. The theme comes from the display — not from you, not from me, from the display. 👑

Cursor XcursorImageLoadCursor(
               Display               *dpy,
               const XcursorImage    *image)

This one creates a cursor, given the image to display. It calls XcursorSupportsARGB to decide what type of cursor to make, and it's a whole vibe check:

• XRenderCreateCursor is used if ARGB is supported on the display, and
• XCreatePixmapCursor is used otherwise.

Cursor XcursorImagesLoadCursor(
               Display               *dpy,
               const XcursorImages   *images)

This is the animated cursor interface 🦋 — it does its thing if the images array contains multiple images, and if XcursorSupportsAnim returns true. Otherwise? It just calls XcursorImageLoadCursor. no animation, we keep it simple.

XcursorCursors *XcursorImagesLoadCursors(
               Display               *dpy,
               const XcursorImages   *images)

This calls XcursorCursorsCreate to create an array of XcursorCursors, so it lines up with the XcursorImages images array, and it uses XcursorImageLoadCursor to load the corresponding cursor data. 🔥

Normally it returns the resulting array pointer. On any failure, it discards the result with XcursorCursorsDestroy, and returns NULL. it said nvm and cleaned up after itself, we respect it. 🙈

---

⭐ X Cursor Name APIs ⭐

XcursorImage *XcursorShapeLoadImage (
               unsigned int           shape,
               const char            *theme,
               int                    size)

XcursorImages *XcursorShapeLoadImages (
               unsigned int           shape,
               const char            *theme,
               int                    size)

These map shape to a library name using the standard X cursor names, and then load the images. 🎨

Cursor XcursorShapeLoadCursor (
               Display               *dpy,
               unsigned int           shape)

XcursorCursors *XcursorShapeLoadCursors (
               Display               *dpy,
               unsigned int           shape)

Same deal — these map shape to a library name, and then load the cursors. 💅

---

🫶 X Cursor Comment APIs 🫶

XcursorComment *XcursorCommentCreate (
               XcursorUInt            comment_type,
               int                    length)

XcursorXcFileLoad uses this function to allocate an XcursorComment structure for a single cursor. The comment_type parameter is used as the subtype field — like, e.g., COPYRIGHT. And length is the number of bytes to allocate for the comment text. 🎀

void XcursorCommentDestroy(
               XcursorComment        *comment)

Deallocates the given XcursorComment structure. bye bestie 👋

XcursorComments * XcursorCommentsCreate (
               int                    size)

XcursorXcFileLoad uses this function to allocate an index of XcursorComment structure pointers. The size parameter tells it how many pointers are gonna be in that index. 🗂️

void XcursorCommentsDestroy (
               XcursorComments       *comments)

Deallocates the given XcursorComments structure, as well as the XcursorComment structures it points to. it takes the whole friend group down with it. 💀

---

🌈 Animated Cursors 🌈

XcursorAnimate * XcursorAnimateCreate (
               XcursorCursors        *cursors)

Wraps the given array of cursors in a newly allocated XcursorAnimate structure — which adds a sequence number that gets used in XcursorAnimateNext. it's giving ✨organized✨.

void XcursorAnimateDestroy (
               XcursorAnimate        *animate)

Discards the given animate data, freeing both the XcursorCursors array of cursors and the XcursorAnimate structure. two for one. 🫶

Cursor XcursorAnimateNext (
               XcursorAnimate        *animate)

Cyclically returns the next Cursor in the array, incrementing the sequence number so it's ready for the next call. 🔁

Heads up bestie: the caller is responsible for displaying the series of Cursor images. Xcursor does not do that. that part is on you, not me. 💅

---

🧚 Glyph Cursor APIs 🧚

The X11 XCreateFontCursor and XCreateGlyphCursor functions use this part of the API to extend the X core cursors feature so it can use themes. iconic behaviour honestly. 👑

void XcursorImageHash (
               XImage                *image,
               unsigned char          hash[XCURSOR_BITMAP_HASH_SIZE])

Computes a hash of the image — this is what gets displayed when the environment variable XCURSOR_DISCOVER is set. 🔍

void XcursorImagesSetName (
               XcursorImages         *images,
               const char            *name)

Associates the given name with the images. cute, now they're labeled. 🏷️

void XcursorNoticeCreateBitmap (
               Display               *dpy,
               Pixmap                 pid,
               unsigned int           width,
               unsigned int           height)

Checks if the display supports either ARGB or themes, and also if the image size fits within the maximum cursor size (64 pixels). If it does, it creates a bitmap of the specified size, and caches the result in Xcursor, identifying it with the Pixmap-id (pid) value. 📌

void XcursorNoticePutBitmap (
               Display               *dpy,
               Drawable               draw,
               XImage                *image)

Updates the image contents in the bitmap specified by the draw value (a Pixmap-id). But listen — the bitmap must have been created by XcursorNoticeCreateBitmap. no shortcuts. 🙅

Cursor XcursorTryShapeBitmapCursor (
               Display               *dpy,
               Pixmap                 source,
               Pixmap                 mask,
               XColor                *foreground,
               XColor                *background,
               unsigned int           x,
               unsigned int           y)

If the display supports either ARGB or themes, it tries to load a cursor into Xcursor's cache using the source parameter as a Pixmap-id. ⚠️ Plot twist: the source may no longer be in the cache. Xcursor uses the hash value to identify the desired image.

Cursor XcursorTryShapeCursor (
               Display               *dpy,
               Font                   source_font,
               Font                   mask_font,
               unsigned int           source_char,
               unsigned int           mask_char,
               XColor _Xconst        *foreground,
               XColor _Xconst        *background)

If the display supports either ARGB or themes, it tries to load a cursor into Xcursor's cache using the source_char parameter as a shape. Using:

• the default size from XcursorGetDefaultSize,
• the default theme from XcursorGetTheme, and
• the source_char parameter as a shape,

Xcursor calls XcursorShapeLoadImages to load the cursor images. And if that's successful, Xcursor uses XcursorImagesLoadCursor to load the cursor information. ✨ full pipeline, we love a workflow.

---

💖 Display Information APIs 💖

XcursorBool XcursorSupportsARGB (
               Display               *dpy)

Returns true if the display supports ARGB cursors. Otherwise, cursors will be mapped to a core X cursor. okay so that's the vibe check, bestie. 💅

XcursorSupportsAnim

       XcursorBool XcursorSupportsAnim (
                      Display               *dpy)

Returns true if the display supports animated cursors. Otherwise, cursors will be mapped to a core X cursor. no cap. ✨

XcursorSetDefaultSize

       XcursorBool XcursorSetDefaultSize (
                      Display               *dpy,
                      int                    size)

Sets the default size for cursors on the specified display. When loading cursors, those whose nominal size is closest to this size will be preferred. periodt. 🎀

XcursorGetDefaultSize

       int XcursorGetDefaultSize (
                      Display               *dpy)

Gets the default cursor size. slay. 🦋

XcursorSetResizable

       XcursorBool XcursorSetResizable (
                      Display               *dpy,
                      XcursorBool            resizable)

Sets the current resizable-cursors state. got it. 💖

XcursorGetResizable

       XcursorBool XcursorGetResizable (
                      Display               *dpy)

Gets the current resizable-cursors state. vibe check. 🌸

XcursorSetTheme

       XcursorBool XcursorSetTheme (
                      Display               *dpy,
                      const char            *theme)

Sets the current theme name. theme queen. 👑

XcursorGetTheme

       char *XcursorGetTheme (
                      Display               *dpy)

Gets the current theme name. periodt. 💜

XcursorGetThemeCore

       XcursorBool XcursorGetThemeCore (
                      Display               *dpy)

XcursorSetThemeCore

       XcursorBool XcursorSetThemeCore (
                      Display               *dpy,
                      XcursorBool            theme_core)

Get or set property which tells Xcursor whether to enable themes for core cursors. iykyk. 🧚

---

✨ ENVIRONMENT ✨

okay so environment variables can be used to override resource settings, which in turn override compiled-in default values. the way that works is lowkey iconic.

Some of the environment variables recognized by Xcursor are booleans, specified as follows:

• true for “t”, “1”, “y” or “on”
• false for “f”, “0”, “n” or “off”

Xcursor ignores other values for these booleans. so don't try to be cute with random strings, bestie. 💀

• HOME — Xcursor interprets “~” in the search list as the home directory, using this variable rather than the password database. fr fr.
• XCURSOR_ANIM — If the display supports the Render CreateCursor request, and the Render feature is enabled, disable animated cursors if the environment variable is false. If the environment variable is not given, Xcursor uses the resource Xcursor.anim. animated cursor drama.
• XCURSOR_CORE — If the display supports the Render CreateCursor request disable the Render feature if the environment variable is false. If the environment variable is not given, Xcursor uses the resource Xcursor.core. core cursor energy.
• XCURSOR_DISCOVER — If the variable is set, Xcursor turns on a logging feature. It displays the hash value and the image so that users can see which cursor name is associated with each image. There is no corresponding resource setting. detective mode activated. 🔍
• XCURSOR_DITHER — This variable sets the desired dither. If the environment variable is not given, Xcursor uses the resource Xcursor.dither. If neither environment variable or resource is found, Xcursor uses “threshold” These are the recognized values:
  • diffuse
  • median
  • ordered
  • threshold
• XCURSOR_PATH — This variable sets the list of paths in which to search for cursors, rather than the compiled-in default list. Directories in this path are separated by colons (:). colon power.
• XCURSOR_RESIZED — Enables automatic resizing of cursors to improve their displayed size if the environment variable is true. If the environment variable is not given, Xcursor tries the Xcursor.resized resource. auto-resize glow-up.
• XCURSOR_SIZE — This variable sets the desired cursor size, in pixels. If the environment variable is not given, Xcursor tries the Xcursor.size resource. If no size is given, whether by environment variable or resource setting, Xcursor next tries the Xft.dpi resource setting to guess the size of a 16-point cursor. Finally, if Xft.dpi is not set, Xcursor uses the display height, dividing by 48 (assuming that the height is 768). math but make it cursor. 😭
• XCURSOR_THEME — This variable selects the desired theme. If the environment variable is not given, Xcursor tries the Xcursor.theme resource. If neither environment variable or resource is found, Xcursor uses the default theme. theme slay.
• XCURSOR_THEME_CORE — Enables themes for core cursors if the environment variable is true. If the environment variable is not given, Xcursor tries the Xcursor.theme_core resource. An application can enable or disable themes using XcursorSetThemeCore. app control, periodt.

---

💀 CAVEATS 💀

okay so Xcursor will probably change radically in the future; weak attempts will be made to retain some level of source-file compatibility. so like, don't get too attached to the internals, bestie. 🙈

---

👑 AUTHORS 👑

• Keith Packard
• Thomas E. Dickey

icons, literally. 💅

---

🔥 SEE ALSO 🔥

• XCreateRenderCursor(3)
• XCreatePixmapCursor(3)
• XCreateFontCursor(3)

as well as

• Icon Theme Specification
• https://specifications.freedesktop.org/icon-theme-spec/

---

source/version: X Version 11 · libXcursor 1.2.3 · page: XCURSOR(3) — and the date slot is giving mysterious, but we're still obsessed. 💅✨