diff mbox series

[FFmpeg-devel] avutil/opt: Document actual behaviour of av_opt_copy a bit more

Message ID AM7PR03MB6660AC198DE17BF2FBAD07ED8FFA9@AM7PR03MB6660.eurprd03.prod.outlook.com
State Accepted
Headers show
Series [FFmpeg-devel] avutil/opt: Document actual behaviour of av_opt_copy a bit more | expand


Context Check Description
andriy/x86_make success Make finished
andriy/x86_make_fate success Make fate finished
andriy/PPC64_make success Make finished
andriy/PPC64_make_fate success Make fate finished

Commit Message

Andreas Rheinhardt Aug. 13, 2021, 7:18 a.m. UTC
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.

Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@outlook.com>
Missing APIchanges entry and version bump (minor or micro?).

 libavutil/opt.h | 7 +++++++
 1 file changed, 7 insertions(+)
diff mbox series


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