XInternAtom(XS)   X Version 11 (Release 5) 6 January 1993    XInternAtom(XS)


 Name

    XInternAtom - create or return atom names

 Syntax


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

    char *XGetAtomName(display, atom)
          Display *display;
          Atom atom;


 Arguments


    atom           Specifies the atom for the property name you want
                   returned.

    atomname      Specifies the name associated with the atom you want
                   returned.

    display        Specifies the connection to the X server.

    onlyifexists Specifies a Boolean value that indicates whether XInternA-
                   tom creates the atom.

 Description

    The XInternAtom function returns the atom identifier associated with the
    specified atomname string.  If onlyifexists is False, the atom is cre-
    ated 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.  Case matters; 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.

    The XGetAtomName function returns the name associated with the specified
    atom.  If the data returned by the server is in the Latin Portable Char-
    acter Encoding, then the returned string is in the Host Portable Charac-
    ter Encoding.  Otherwise, the result is implementation dependent.  To
    free the resulting string, call XFree.

    XGetAtomName can generate a ``BadAtom'' error.

 Diagnostics


    ``BadAlloc''   The server failed to allocate the requested resource or
                   server memory.

    ``BadAtom''    A value for an Atom argument does not name a defined Atom.

    ``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(XS), XGetWindowProperty(XS)
    Xlib - C Language X Interface