#pragma section-numbers off
#pragma camelcase off

= SDL_AllocRW =
Use this function to allocate an empty, unpopulated [[SDL_RWops]] structure.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
SDL_RWops* SDL_AllocRW(void)
}}}

== Return Value ==
Returns a pointer to the allocated memory on success, or NULL on failure; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
#include "stdlib.h"
#include "SDL.h"

/* These functions should not be used except from pointers in an SDL_RWops */
static Sint64 mysizefunc(SDL_RWops * context)
{
  return -1;
}

static Sint64 myseekfunc(SDL_RWops *context, Sint64 offset, int whence)
{
  return SDL_SetError("Can't seek in this kind of SDL_RWops");
}

static size_t myreadfunc(SDL_RWops *context, void *ptr, size_t size, size_t maxnum)
{
  SDL_memset(ptr,0,size*maxnum);
  return maxnum;
}

static size_t mywritefunc(SDL_RWops *context, const void *ptr, size_t size, size_t num)
{
  return num;
}

static int myclosefunc(SDL_RWops *context)
{
  if(context->type != 0xdeadbeef)
  {
    return SDL_SetError("Wrong kind of SDL_RWops for myclosefunc()");
  }

  free(context->hidden.unknown.data1);
  SDL_FreeRW(context);
  return 0;
}

SDL_RWops *MyCustomRWop()
{
  SDL_RWops *c=SDL_AllocRW();
  if(c==NULL) return NULL;

  c->size =mysizefunc;
  c->seek =myseekfunc;
  c->read =myreadfunc;
  c->write=mywritefunc;
  c->close=myclosefunc;
  c->type =0xdeadbeef;
  c->hidden.unknown.data1=malloc(256);
  return c;
}
}}}

== Remarks ==
Applications do not need to use this function unless they are providing their own [[SDL_RWops]] implementation. If you just need a SDL_RWops to read/write a common data source, you should use the built-in implementations in SDL, like [[SDL_RWFromFile]]() or [[SDL_RWFromMem]](), etc.

You must free the returned pointer with [[SDL_FreeRW]](). Depending on your operating system and compiler, there may be a difference between the malloc() and free() your program uses and the versions SDL calls internally. Trying to mix the two can cause crashing such as segmentation faults. Since all SDL_RWops must free themselves when their '''close''' method is called, all SDL_RWops must be allocated through this function, so they can all be freed correctly with [[SDL_FreeRW]]().

== Related Functions ==
 .[[SDL_FreeRW]]

----
[[CategoryAPI]], [[CategoryIO]]