[asterisk-dev] stringfields doc bug leading to memory leaks

[Luigi Rizzo]

I have a longer message coming up, but just noticed that stringfields.h
says that ast_string_field_free_all() is enough to release storage:

	....
  When the structure instance is no longer needed, the fields
  and their storage pool must be freed:
  
  \code
  ast_string_field_free_all(sample);
  free(sample);
  \endcode


However if you look at the code, ast_string_field_free_all() does not
release the pools - you have to call ast_string_field_free_pools()
instead.

Now: some files (app_meetme.c and res_features.c) believe the documentation
and thus leak memory. Some others (chan_sip.c, chan_iax2.c, channel.c)
believe the code and call ast_string_field_free_pools(). In both cases
it appears that the intention is to free all memory, not to invalidate
all strings in the stringfield.

So how do we fix this ? In cases like these, I would probably come up
with a newer name (just to avoid confusion with older code) for the
routine to free memory, and get rid of the other one which is never
used.

So are you ok with creating

	ast_string_field_free_memory(x)

to free all memory pools (and if you really want to play safe, also
invalidate pointers), and remove the two old ones, ast_string_field_free_all()
and ast_string_field_free_pools() ?

For 1.4 if one wants to keep a bit of source-level compatibility we
could just redefine the old macros to ast_string_field_free_memory()
and mark them as deprecated.