libctf: add a comment explaining how to use ctf_*open

Specifically, tell users what to pass to those functions that accept raw
section content, since it's fairly involved and easy to get wrong.
(.dynsym / .dynstr when CTF_F_DYNSTR is set, otherwise .symtab / .strtab).

include/ChangeLog:

	* ctf-api.h (ctf_*open): Improve comment.

diff --git a/include/ctf-api.h b/include/ctf-api.h
index a3f45283b3cca1bc0e5a6b78feaa33d55033c2a2..153e012b5a0fed37aa674b06c9648da5ecb85c79 100644 (file)
--- a/include/ctf-api.h
+++ b/include/ctf-api.h
@@ -314,7 +314,13 @@ extern ctf_next_t *ctf_next_copy (ctf_next_t *);
    archives: so they can be used to open both.  CTF files will appear to be an
    archive with one member named '.ctf'.  The low-level functions
    ctf_simple_open and ctf_bufopen return ctf_dict_t's directly, and cannot
-   be used on CTF archives.  */
+   be used on CTF archives.
+
+   Some of these functions take raw symtab and strtab section content in the
+   form of ctf_sect_t structures.  For CTF in ELF files, these should be
+   extracted from .dynsym and its associated string table (usually .dynsym)
+   whenever the CTF_F_DYNSTR flag is set in the CTF preamble (which it almost
+   always will be for linked objects, but not for .o files).  */
 
 extern ctf_archive_t *ctf_bfdopen (struct bfd *, int *);
 extern ctf_archive_t *ctf_bfdopen_ctfsect (struct bfd *, const ctf_sect_t *,