From bc5a1047548b578624cfbc44ca192cde7664ed78 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Fri, 13 Jun 2014 21:26:21 -0700 Subject: [PATCH] Document failure modes of xcb_connect*() functions Documentation was previously unclear that these always return a non-NULL pointer, and that callers need to check it for error values, instead of checking for a NULL return value. Triggered by having to dig through code to answer a user's question on the #xcb irc channel, since neither of us found it covered in the docs. Signed-off-by: Alan Coopersmith Reviewed-by: Uli Schlachter --- src/xcb.h | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/xcb.h b/src/xcb.h index c17a2ef..0bf59d0 100644 --- a/src/xcb.h +++ b/src/xcb.h @@ -453,7 +453,8 @@ int xcb_get_file_descriptor(xcb_connection_t *c); * Some errors that occur in the context of an xcb_connection_t * are unrecoverable. When such an error occurs, the * connection is shut down and further operations on the - * xcb_connection_t have no effect. + * xcb_connection_t have no effect, but memory will not be freed until + * xcb_disconnect() is called on the xcb_connection_t. * * @return XCB_CONN_ERROR, because of socket errors, pipe errors or other stream errors. * @return XCB_CONN_CLOSED_EXT_NOTSUPPORTED, when extension not supported. @@ -475,6 +476,11 @@ int xcb_connection_has_error(xcb_connection_t *c); * bidirectionally connected to an X server. If the connection * should be unauthenticated, @p auth_info must be @c * NULL. + * + * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. + * Callers need to use xcb_connection_has_error() to check for failure. + * When finished, use xcb_disconnect() to close the connection and free + * the structure. */ xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info); @@ -520,6 +526,11 @@ int xcb_parse_display(const char *name, char **host, int *display, int *screen); * variable. If a particular screen on that server is preferred, the * int pointed to by @p screenp (if not @c NULL) will be set to that * screen; otherwise the screen will be set to 0. + * + * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. + * Callers need to use xcb_connection_has_error() to check for failure. + * When finished, use xcb_disconnect() to close the connection and free + * the structure. */ xcb_connection_t *xcb_connect(const char *displayname, int *screenp); @@ -534,6 +545,11 @@ xcb_connection_t *xcb_connect(const char *displayname, int *screenp); * authorization @p auth. If a particular screen on that server is * preferred, the int pointed to by @p screenp (if not @c NULL) will * be set to that screen; otherwise @p screenp will be set to 0. + * + * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. + * Callers need to use xcb_connection_has_error() to check for failure. + * When finished, use xcb_disconnect() to close the connection and free + * the structure. */ xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen); -- 2.34.1