[Xcb] [PATCH v2:libxcb] Document failure modes of xcb_connect*() functions

[Uli Schlachter]

On 14.06.2014 06:29, Alan Coopersmith wrote:
> 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 <alan.coopersmith at oracle.com>

Reviewed-by: Uli Schlachter <psychon at znc.in>

> ---
> 
>  Reworded somewhat following the suggestions by Uli.

Thanks, I like this version even more.

(And v1 is now also marked as superseded in patchwork)

> 
>  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);
>  
> 


-- 
"Every once in a while, declare peace. It confuses the hell out of your enemies"
 - 79th Rule of Acquisition