X-Git-Url: https://git.distorted.org.uk/~mdw/catacomb/blobdiff_plain/0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a..8f2287ef5c05d496fcb9b012629af007fe56f897:/key/key.h

diff --git a/key/key.h b/key/key.h
index bed36325..96a2b5a2 100644
--- a/key/key.h
+++ b/key/key.h
@@ -177,36 +177,64 @@ typedef void key_reporter(const char */*file*/, int /*line*/,
 
 /*----- Reading and writing keys and files --------------------------------*/
 
-/* --- @key_merge@ --- *
+/* --- @key_merge@, @key_mergeline@ --- *
  *
  * Arguments:	@key_file *f@ = pointer to file structure
  *		@const char *file@ = name of file (for error messages)
- *		@FILE *fp@ = file handle to read from
+ *		@int lno@ = line number (for error messages, @key_mergeline@)
+ *		@FILE *fp@ = file handle to read from (@key_merge@)
+ *		@const char *line@ = line from the input (@key_mergeline@)
  *		@key_reporter *rep@ = error reporting function
  *		@void *arg@ = argument for function
  *
  * Returns:	Error code (one of the @KERR@ constants).
  *
- * Use:		Reads keys from a file, and inserts them into the file.
+ * Use:		The @key_merge@ function reads keys from a file, and inserts
+ *		them into the keyring.
+ *
+ *		The @key_mergeline@ function reads a key from a single input
+ *		line (which may, but need not, have a final newline), and
+ *		adds it to the keyring.
+ *
+ *		The @key_mergeline@ function is intended to help with
+ *		interfacing Catacomb to runtimes which don't use C's @stdio@
+ *		streams, rather than as a general-purpose service, though if
+ *		it turns out to be useful in other ways then so much the
+ *		better.
  */
 
 extern int key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/,
 		     key_reporter */*rep*/, void */*arg*/);
+extern int key_mergeline(key_file */*f*/, const char */*file*/, int /*lno*/,
+			 const char */*line*/,
+			 key_reporter */*rep*/, void */*arg*/);
 
-/* --- @key_extract@ --- *
+/* --- @key_extract@, @key_extractline@ --- *
  *
  * Arguments:	@key_file *f@ = pointer to file structure
  *		@key *k@ = key to extract
- *		@FILE *fp@ = file to write on
+ *		@FILE *fp@ = file to write on (@key_extract@)
+ *		@dstr *d@ = string to write on (@key_extractline@)
  *		@const key_filter *kf@ = pointer to key selection block
  *
- * Returns:	Zero if OK, EOF on error.
+ * Returns:	@key_extract@ returns zero if OK, EOF on error.
+ *		@key_extractline@ does not return a value.
+ *
+ * Use:		Extracts a key to an ouptut file or buffer.
+ *
+ *		The @key_extractline@ includes a final newline in its output.
  *
- * Use:		Extracts a key to an ouptut file.
+ *		The @key_extractline@ function is intended to help with
+ *		interfacing Catacomb to runtimes which don't use C's @stdio@
+ *		streams, rather than as a general-purpose service, though if
+ *		it turns out to be useful in other ways then so much the
+ *		better.
  */
 
 extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/,
 		       const key_filter */*kf*/);
+extern void key_extractline(key_file */*f*/, key */*k*/,
+			    dstr */*d*/, const key_filter */*kf*/);
 
 /* --- @key_open@ --- *
  *