avutil/opt: Document actual behaviour of av_opt_copy a bit more

In particular, document that av_opt_copy() always disentangles
allocated options even on error; this guarantee is needed to e.g.
properly free duplicated thread contexts in libavcodec on error.

Reviewed-by: Michael Niedermayer <michael@niedermayer.cc>
Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@outlook.com>

1 files changed, 7 insertions, 0 deletions

diff --git a/libavutil/opt.h b/libavutil/opt.h
index 9e1e8ede06..2820435eec 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -790,9 +790,16 @@ int av_opt_query_ranges(AVOptionRanges **, void *obj, const char *key, int flags
 /**
  * Copy options from src object into dest object.
  *
+ * The underlying AVClass of both src and dest must coincide. The guarantee
+ * below does not apply if this is not fulfilled.
+ *
  * Options that require memory allocation (e.g. string or binary) are malloc'ed in dest object.
  * Original memory allocated for such options is freed unless both src and dest options points to the same memory.
  *
+ * Even on error it is guaranteed that allocated options from src and dest
+ * no longer alias each other afterwards; in particular calling av_opt_free()
+ * on both src and dest is safe afterwards if dest has been memdup'ed from src.
+ *
  * @param dest Object to copy from
  * @param src  Object to copy into
  * @return 0 on success, negative on error