API design - allocate output?

Question

Is it a good idea for C API functions to allocate their output, or to have the user specify the output buffer? For example:

BOOL GetString(
    PWSTR *String
    );
...
PWSTR string;
GetString(&string);
Free(string);

vs

BOOL GetString(
    PWSTR Buffer,
    ULONG BufferSize,
    PULONG RequiredBufferSize
    );
...
// A lot more code than in the first case

More specifically I'm wondering why the Win32 API primarily uses the second case (e.g. GetWindowText, LookupAccountSid). If an API function knows how big the output is, why have the user try to guess the output size? I can't find any information on why the second case would be used.

Also: the LookupAccountSid example is particularly bad. Internally it uses the LSA API, which allocates the output for the caller. Then LookupAccountSid gets the user to allocate a buffer (and guess the correct buffer size) when it could just return the output from LSA! Why?

Answer 1

The Win32 API does not pre-allocate buffers because it wants to give the calling code the choice of how to provide the buffer. It allows for them to provide stack and a variety of heap based buffers. There are several places where the maximum size of the buffer is known ahead of time and developers want the simplicity of using a stack based buffer.

The file system is the best example as paths won't exceed MAX_PATH. So rather than allocate + free. The developer simply declares a stack based buffer.

The advantage to having the C API allocate memory is that it simplifies the calling pattern. The downside of the Win32 pattern is that most times you end up calling the API twice. The first time to determine the size of the buffer, then the second time with a buffer of appropriate size. With an API allocated buffer only one call is needed.

The downside though is that you take away the choice of allocation from the caller. Additionally you must communicate your choice in order for them to properly free the API (windows for instance can allocate from several different places).

Answer 2

The second approach has some advantages like

• It lets callers manage the lifetime of memory allocations
• It lets callers to reuse allocated memory for different calls that follow that same pattern
• It lets callers to decide which buffer to provide e.g. stack or heap.