XInternAtom

Syntax

Atom XInternAtom(display, atom_name, only_if_exists)
      Display *display;
      char *atom_name;
      Bool only_if_exists;

Arguments

display Specifies the connection to the X server.
atom_name Specifies the name associated with the atom you want returned.
only_if_exists Specifies a Boolean value that indicates whether the atom must be created.

Description

The XInternAtom() function returns the atom identifier associated with the specified atom_name string. If only_if_exists is False, the atom is created if it does not exist. Therefore, XInternAtom() can return None. If the atom name is not in the Host Portable Character Encoding, the result is implementation dependent. Uppercase and lowercase matter; the strings ``thing'', ``Thing'', and ``thinG'' all designate different atoms. The atom will remain defined even after the client's connection closes. It will become undefined only when the last connection to the X server closes.

XInternAtom() can generate BadAlloc and BadValue errors.

Diagnostics

BadAlloc The server failed to allocate the requested source or server memory.
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.

See also

XFree(), XGetAtomName(), XGetWindowProperty(), XInternAtoms(), "Properties and Atoms"
Christophe Tronche, ch@tronche.com