NAME

XInternAtom, XInternAtoms, XGetAtomName, XGetAtomNames - create or return atom names

SYNTAX

Atom XInternAtom(Display *_d_i_s_p_l_a_y, char *_a_t_o_m___n_a_m_e, Bool _o_n_l_y___i_f___e_x_i_s_t_s); Status XInternAtoms(Display *_d_i_s_p_l_a_y, char **_n_a_m_e_s, int _c_o_u_n_t, Bool _o_n_l_y___i_f___e_x_i_s_t_s, Atom *_a_t_o_m_s___r_e_t_u_r_n); char *XGetAtomName(Display *_d_i_s_p_l_a_y, Atom _a_t_o_m); Status XGetAtomNames(Display *_d_i_s_p_l_a_y, Atom *_a_t_o_m_s, int _c_o_u_n_t, char **_n_a_m_e_s___r_e_t_u_r_n);

ARGUMENTS

_a_t_o_m Specifies the atom for the property name you want returned.
_a_t_o_m_s Specifies the array of atoms.
_a_t_o_m___n_a_m_e Specifies the name associated with the atom you want returned.
_a_t_o_m_s___r_e_t_u_r_n Returns the atoms.
_c_o_u_n_t Specifies the number of atom names in the array.
_c_o_u_n_t Specifies the number of atoms in the array.
_d_i_s_p_l_a_y Specifies the connection to the X server.
_n_a_m_e_s Specifies the array of atom names.
_n_a_m_e_s___r_e_t_u_r_n Returns the atom names.
_o_n_l_y___i_f___e_x_i_s_t_s Specifies a Boolean value that indicates whether the atom must be created.

DESCRIPTION

The _X_I_n_t_e_r_n_A_t_o_m function returns the atom identifier associated with the specified atom_name string. If only_if_exists is _F_a_l_s_e, the atom is created if it does not exist. Therefore, _X_I_n_t_e_r_n_A_t_o_m can return _N_o_n_e. 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.

_X_I_n_t_e_r_n_A_t_o_m can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.

The _X_I_n_t_e_r_n_A_t_o_m_s function returns the atom identifiers associated with the specified names. The atoms are stored in the atoms_return array supplied by the caller. Calling this function is equivalent to calling _X_I_n_t_e_r_n_A_t_o_m for each of the names in turn with the specified value of only_if_exists, but this function minimizes the number of round-trip protocol exchanges between the client and the X server.

This function returns a nonzero status if atoms are returned for all of the names; otherwise, it returns zero.

_X_I_n_t_e_r_n_A_t_o_m_s can generate _B_a_d_A_l_l_o_c and _B_a_d_V_a_l_u_e errors.

The _X_G_e_t_A_t_o_m_N_a_m_e function returns the name associated with the specified atom. If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. To free the resulting string, call _X_F_r_e_e.

_X_G_e_t_A_t_o_m_N_a_m_e can generate a _B_a_d_A_t_o_m error.

The _X_G_e_t_A_t_o_m_N_a_m_e_s function returns the names associated with the specified atoms. The names are stored in the names_return array supplied by the caller. Calling this function is equivalent to calling _X_G_e_t_A_t_o_m_N_a_m_e for each of the atoms in turn, but this function minimizes the number of round-trip protocol exchanges between the client and the X server.

This function returns a nonzero status if names are returned for all of the atoms; otherwise, it returns zero.

_X_G_e_t_A_t_o_m_N_a_m_e_s can generate a _B_a_d_A_t_o_m error.

DIAGNOSTICS

_B_a_d_A_l_l_o_c
The server failed to allocate the requested resource or server memory.
_B_a_d_A_t_o_m
A value for an Atom argument does not name a defined Atom.
_B_a_d_V_a_l_u_e
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(3X11), XGetWindowProperty(3X11)
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e