Jonathan Nieder <jrnieder@xxxxxxxxx> writes: > strbuf_release leaves the strbuf in a valid, initialized state, so > there is no need to call strbuf_init after it. > > Moreover, this is not likely to change in the future: strbuf_release > leaving the strbuf in a valid state has been easy to maintain and has > been very helpful for Git's robustness and simplicity (e.g., > preventing use-after-free vulnerabilities). > > Document the semantics so the next generation of Git developers can > become familiar with them without reading the implementation. It is > still not advisable to call strbuf_release too often because it is > wasteful, so add a note pointing to strbuf_reset for that. > > The same semantics apply to strbuf_detach. Add a similar note to its > docstring to make that clear. > > Improved-by: Jeff King <peff@xxxxxxxx> > Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> > --- > Jeff King wrote: > >> I think it's actually OK to use the string buffer after this function. >> It's just an empty string. >> >> Perhaps we should be more explicit: this releases any resources and >> resets to a pristine, empty state. I suspect strbuf_detach() probably >> should make the same claim. > > Like this? Looks good to me. > > Thanks, > Jonathan > > strbuf.h | 11 +++++++++-- > 1 file changed, 9 insertions(+), 2 deletions(-) > > diff --git a/strbuf.h b/strbuf.h > index 7496cb8ec5..249df86711 100644 > --- a/strbuf.h > +++ b/strbuf.h > @@ -82,8 +82,12 @@ extern char strbuf_slopbuf[]; > extern void strbuf_init(struct strbuf *, size_t); > > /** > - * Release a string buffer and the memory it used. You should not use the > - * string buffer after using this function, unless you initialize it again. > + * Release a string buffer and the memory it used. After this call, the > + * strbuf points to an empty string that does not need to be free()ed, as > + * if it had been set to `STRBUF_INIT` and never modified. > + * > + * To clear a strbuf in preparation for further use without the overhead > + * of free()ing and malloc()ing again, use strbuf_reset() instead. > */ > extern void strbuf_release(struct strbuf *); > > @@ -91,6 +95,9 @@ extern void strbuf_release(struct strbuf *); > * Detach the string from the strbuf and returns it; you now own the > * storage the string occupies and it is your responsibility from then on > * to release it with `free(3)` when you are done with it. > + * > + * The strbuf that previously held the string is reset to `STRBUF_INIT` so > + * it can be reused after calling this function. > */ > extern char *strbuf_detach(struct strbuf *, size_t *);
