SDL Wiki
(This is the documentation for SDL3, which is under heavy development and the API is changing! SDL2 is the current stable version!)


Read from a data source.


Sint64 SDL_RWread(SDL_RWops *context, void *ptr, Sint64 size);

Function Parameters

context a pointer to an SDL_RWops structure
ptr a pointer to a buffer to read data into
size the number of bytes to read from the data source.

Return Value

Returns the number of bytes read, 0 at end of file, -1 on error, and -2 for data not ready with a non-blocking context.


This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested. It will return zero when the data stream is completely read, or -1 on error. For streams that support non-blocking operation, if nothing was read because it would require blocking, this function returns -2 to distinguish that this is not an error or end-of-file, and the caller can try again later.

SDL_RWread() is actually a function wrapper that calls the SDL_RWops's read method appropriately, to simplify application development.

It is an error to specify a negative size, but this parameter is signed so you definitely cannot overflow the return value on a successful run with enormous amounts of data.


This function is available since SDL 3.0.0.

Code Examples

SDL_RWops *rw = SDL_RWFromFile("test.bin","r");
if (rw != NULL) {
    extern Uint8 buf[256];
    SDL_RWread(rw, buf, sizeof (buf), 1);

Read a complete file in memory (assuming size can be detected) (from OpenGL WikiBook):

char* file_read(const char* filename) {
    SDL_RWops *rw = SDL_RWFromFile(filename, "rb");
    if (rw == NULL) return NULL;

    Sint64 res_size = SDL_RWsize(rw);
    char* res = (char*)malloc(res_size + 1);

    Sint64 nb_read_total = 0, nb_read = 1;
    char* buf = res;
    while (nb_read_total < res_size && nb_read != 0) {
        nb_read = SDL_RWread(rw, buf, 1, (res_size - nb_read_total));
        nb_read_total += nb_read;
        buf += nb_read;
    if (nb_read_total != res_size) {
        return NULL;

    res[nb_read_total] = '\0';
    return res;

CategoryAPI, CategoryIO

[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.