diff --git a/libavformat/avio.c b/libavformat/avio.c
index e91bc200db..706ba4a610 100644
--- a/libavformat/avio.c
+++ b/libavformat/avio.c
@@ -156,8 +156,10 @@ int url_read_complete(URLContext *h, unsigned char *buf, int size)
     len = 0;
     while (len < size) {
         ret = url_read(h, buf+len, size-len);
-        if (ret < 1)
-            return ret;
+        if (ret == AVERROR(EAGAIN)) {
+            ret = 0;
+        } else if (ret < 1)
+            return ret < 0 ? ret : len;
         len += ret;
     }
     return len;
diff --git a/libavformat/avio.h b/libavformat/avio.h
index 5aa24ca0a7..39c1ce5178 100644
--- a/libavformat/avio.h
+++ b/libavformat/avio.h
@@ -69,6 +69,14 @@ int url_open_protocol (URLContext **puc, struct URLProtocol *up,
                        const char *filename, int flags);
 int url_open(URLContext **h, const char *filename, int flags);
 int url_read(URLContext *h, unsigned char *buf, int size);
+/**
+ * Read as many bytes as possible (up to size), calling the
+ * read function multiple times if necessary.
+ * Will also retry if the read function returns AVERROR(EAGAIN).
+ * This makes special short-read handling in applications
+ * unnecessary, if the return value is < size then it is
+ * certain there was either an error or the end of file was reached.
+ */
 int url_read_complete(URLContext *h, unsigned char *buf, int size);
 int url_write(URLContext *h, unsigned char *buf, int size);
 int64_t url_seek(URLContext *h, int64_t pos, int whence);