From 571774138cb7c51d40d130bbe2eb3656e6338ff8 Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Wed, 10 Apr 2024 13:52:10 +1000
Subject: [PATCH] sv_setsv_cow: add some documentation

---
 embed.fnc |  2 +-
 sv.c      | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/embed.fnc b/embed.fnc
index e3b27dc1b192..fae0554d6a7c 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -3979,7 +3979,7 @@ RTp	|MEM_SIZE|malloc_good_size					\
 #endif
 #if defined(PERL_ANY_COW)
 : Used in regexec.c
-EXpx	|bool	|sv_setsv_cow	|NN SV **pdsv				\
+EXdpx	|bool	|sv_setsv_cow	|NN SV **pdsv				\
 				|NN SV *ssv
 #endif
 #if defined(PERL_CORE)
diff --git a/sv.c b/sv.c
index eee41a5a38f9..64c462625895 100644
--- a/sv.c
+++ b/sv.c
@@ -4887,6 +4887,29 @@ Perl_sv_setsv_mg(pTHX_ SV *const dsv, SV *const ssv)
     SvSETMAGIC(dsv);
 }
 
+/*
+=for apidoc sv_setsv_cow
+
+Attempt to make a COW copy of C<ssv> in C<*dsv>.
+
+C<*pdsv> must be NULL or a valid SV, if NULL it will be filled in with
+a valid SV on success.
+
+C<ssv> must be a POK, pPOK SV.
+
+Returns true if the copy succeeds, false if a CoW copy cannot be made
+for some reason.
+
+sv_setsv_cow() is used by the regular expression engine to attempt to
+make a COW copy of the matched against string for use in reporting
+C<$1> etc.
+
+If this fails the regular expression engine instead makes a non-SV
+copy of a subset of the matched against string.
+
+=cut
+*/
+
 #ifdef PERL_ANY_COW
 #  define SVt_COW SVt_PV
 bool