client: check for error in wl_display_read_events

This prevents from blocking shown in one display test. Also, it
makes sense to not proceed further in the code of the function
when an error ocurred.

v2. set errno
    put note about the errno into wl_display_prepare_read doc
    check for error with mutex locked

v3.
    set errno to display->last_error

    check for the error only in wl_display_read_events. It's sufficient
    as prevention for the hanging and programmer doesn't need to
    check if wl_display_prepare_read (that was previously covered by
    this patch too) returned an error or the queue just was not empty.
    Without the check, it could result in indefinite looping.

Thanks to Pekka Paalanen <pekka.paalanen@collabora.co.uk> for
constant reviewing and discussing this patch.

Signed-off-by: Marek Chalupa <mchqwerty@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>