libctf: serialize: user control over BTF-versus-CTF writeout

We need some way for users to declare that they want BTF or CTF in
particular to be written out when they ask for it, or that they don't mind
which.  Adding this to all the ctf_write functions (like the compression
threshold already is) would be a bit of a nightmare: there are a great many
of them and this doesn't seem like something people would want to change
on a per-dict basis (even if we did, we'd need to think about archives and
linking, which work on a higher level than single dicts).

So we repurpose an unused, vestigial existing function, ctf_version(), which
was originally intended to do some sort of rather unclear API switching at
runtime, to allow switching between different CTF file format versions (not
yet supported, you have to pass CTF_VERSION) and BTF writeout modes:

/* BTF/CTF writeout version info.

   ctf_btf_mode has three levels:

   - LIBCTF_BTM_ALWAYS writes out full-blown CTFv4 at all times
   - LIBCTF_BTM_POSSIBLE writes out CTFv4 if needed to avoid information loss,
     BTF otherwise.  If compressing, the same as LIBCTF_BTM_ALWAYS.
   - LIBCTF_BTM_BTF writes out BTF always, and errors otherwise.

   Note that no attempt is made to downgrade existing CTF dicts to BTF: if you
   read in a CTF dict and turn on LIBCTF_BTM_POSSIBLE, you'll get a CTF dict; if
   you turn on LIBCTF_BTM_BTF, you'll get an unconditional error.  Thus, this is
   really useful only when reading in BTF dicts or when creating new dicts.  */

typedef enum ctf_btf_mode
{
  LIBCTF_BTM_BTF = 0,
  LIBCTF_BTM_POSSIBLE = 1,
  LIBCTF_BTM_ALWAYS = 2
} ctf_btf_mode_t;

/* Set the CTF library client version to the specified version: this is the
   version of dicts written out by the ctf_write* functions.  If version is
   zero, we just return the default library version number.  The BTF version
   (for CTFv4 and above) is indicated via btf_hdr_len, also zero for "no
   change".

    You can influence what type kinds are written out to a CTFv4 dict via the
    ctf_write_suppress_kind() function.  */

extern int ctf_version (int ctf_version_, size_t btf_hdr_len,
			ctf_btf_mode_t btf_mode);

(We retain the ctf_version_ stuff to leave space in the API to let the
library possibly do file format downgrades in future, since we've already
had requests for such things from users.)

libctf/ctf-api.c

@@ -27,33 +27,63 @@
 #define ENOTSUP ENOSYS
 #endif
 
-int _libctf_version = CTF_VERSION;	      /* Library client version.  */
-int _libctf_debug = 0;			      /* Debugging messages enabled.  */
+static int _libctf_version = CTF_VERSION;     /* Library client version.  */
+static size_t _btf_hdr_len = sizeof (ctf_btf_header_t);
+static int _libctf_debug = 0;		      /* Debugging messages enabled.  */
 
-/* Set the CTF library client version to the specified version.  If version is
-   zero, we just return the default library version number.  */
+ctf_btf_mode_t _libctf_btf_mode = LIBCTF_BTM_POSSIBLE;	/* BTF writeout mode.  */
+
+/* Set the CTF library client version to the specified version: this is the
+   version of dicts written out by the ctf_write* functions.  If version is
+   zero, we just return the default library version number.  The BTF version
+   (for CTFv4 and above) is indicated via btf_hdr_len, also zero for "no
+   change".
+
+   btf_mode has three levels:
+
+    - LIBCTF_BTM_ALWAYS writes out full-blown CTFv4 at all times
+    - LIBCTF_BTM_POSSIBLE writes out CTFv4 if needed to avoid
+      information loss, BTF otherwise (and always writes out CTFv4
+      if compressing)
+    - LIBCTF_BTM_BTF writes out BTF always, and errors otherwise (e.g.
+      if compressing)
+
+    You can influence what type kinds are written out to a CTFv4 dict via the
+    ctf_write_suppress_kind() function.  */
 int
-ctf_version (int version)
+ctf_version (int ctf_version_, size_t btf_hdr_len, ctf_btf_mode_t btf_mode)
 {
-  if (version < 0)
+  if (ctf_version_ < 0 || btf_mode < 0 || btf_mode > 2)
     {
       errno = EINVAL;
       return -1;
     }
 
-  if (version > 0)
+  if (ctf_version_ > 0)
     {
       /*  Dynamic version switching is not presently supported. */
-      if (version != CTF_VERSION)
-	{
-	  errno = ENOTSUP;
-	  return -1;
-	}
-      ctf_dprintf ("ctf_version: client using version %d\n", version);
-      _libctf_version = version;
+      if (ctf_version_ != _libctf_version)
+	goto err;
+
+      ctf_dprintf ("ctf_version: client using version %i\n", ctf_version_);
     }
 
-  return _libctf_version;
+  if (btf_hdr_len > 0)
+    {
+      /*  Dynamic version switching is not presently supported. */
+      if (btf_hdr_len != _btf_hdr_len)
+	goto err;
+
+      ctf_dprintf ("ctf_version: client using BTF header length %zi\n", btf_hdr_len);
+    }
+
+  _libctf_btf_mode = btf_mode;
+
+  return ctf_version_;
+
+ err:
+  errno = ENOTSUP;
+  return -1;
 }
 
 /* Store the specified error code into errp if it is non-NULL, and then