common: More accurately name function.
[gnupg.git] / common / iobuf.h
index b65ea60..785efdc 100644 (file)
@@ -124,12 +124,15 @@ enum iobuf_use
     /* Pipeline is in input mode.  The data flows from the end to the
        beginning.  That is, when reading from the pipeline, the first
        filter gets its input from the second filter, etc.  */
-    IOBUF_INPUT=1,
+    IOBUF_INPUT,
+    /* Pipeline is in input mode.  The last filter in the pipeline is
+       a temporary buffer from which the data is "read".  */
+    IOBUF_INPUT_TEMP,
     /* Pipeline is in output mode.  The data flows from the beginning
        to the end.  That is, when writing to the pipeline, the user
        writes to the first filter, which transforms the data and sends
        it to the second filter, etc.  */
-    IOBUF_OUTPUT=2,
+    IOBUF_OUTPUT,
     /* Pipeline is in output mode.  The last filter in the pipeline is
        a temporary buffer that grows as necessary.  */
     IOBUF_OUTPUT_TEMP
@@ -274,7 +277,8 @@ int  iobuf_is_pipe_filename (const char *fname);
    create a new primary source or primary sink, i.e., the last filter
    in the pipeline.
 
-   USE is IOBUF_INPUT, IOBUF_OUTPUT or IOBUF_OUTPUT_TEMP.
+   USE is IOBUF_INPUT, IOBUF_INPUT_TEMP, IOBUF_OUTPUT or
+   IOBUF_OUTPUT_TEMP.
 
    BUFSIZE is the desired internal buffer size (that is, the size of
    the typical read / write request).  */
@@ -400,10 +404,9 @@ int iobuf_cancel (iobuf_t iobuf);
        called on the pipeline.
 
      IOBUFCTRL_DESC: Called with this value to get a human-readable
-       description of the filter.  * (char **) BUF should set to the
-       NUL-terminated string.  Note: you need to keep track of this
-       value and, if necessary, free it when the filter function is
-       called with control set to IOBUFCTRL_FREE.
+       description of the filter.  *LEN is the size of the buffer.
+       The description is filled into BUF, NUL-terminated.  Always
+       returns 0.
   */
 int iobuf_push_filter (iobuf_t a, int (*f) (void *opaque, int control,
                                            iobuf_t chain, byte * buf,
@@ -422,7 +425,7 @@ int iobuf_push_filter2 (iobuf_t a,
    IOBUF_DEBUG_MODE is not 0.  */
 int iobuf_print_chain (iobuf_t a);
 
-/* Indicate that some error occured on the specified filter.  */
+/* Indicate that some error occurred on the specified filter.  */
 #define iobuf_set_error(a)    do { (a)->error = 1; } while(0)
 
 /* Return any pending error on filter A.  */
@@ -454,7 +457,7 @@ off_t iobuf_tell (iobuf_t a);
      That is, data is appended to the buffer and the seek does not
      cause the size of the buffer to grow.
 
-   If no error occured, then any limit previous set by
+   If no error occurred, then any limit previous set by
    iobuf_set_limit() is cleared.  Further, any error on the filter
    (the file filter or the temp filter) is cleared.
 
@@ -548,6 +551,14 @@ int iobuf_write_temp (iobuf_t dest, iobuf_t source);
    BUFFER.  Returns the number of bytes actually copied.  */
 size_t iobuf_temp_to_buffer (iobuf_t a, byte * buffer, size_t buflen);
 
+/* Copies the data from the input iobuf SOURCE to the output iobuf
+   DEST until either an error is encountered or EOF is reached.
+   Returns the number of bytes successfully written.  If an error
+   occurred, then any buffered bytes are not returned to SOURCE and are
+   effectively lost.  To check if an error occurred, use
+   iobuf_error.  */
+size_t iobuf_copy (iobuf_t dest, iobuf_t source);
+
 /* Return the size of any underlying file.  This only works with
    file_filter based pipelines.
 
@@ -581,7 +592,7 @@ const char *iobuf_get_fname_nonnull (iobuf_t a);
    length headers (see Section 4.2.2.4 of RFC 4880).  Concretely, it
    just returns / writes the data and finishes the packet with an
    EOF.  */
-void iobuf_set_partial_block_mode (iobuf_t a, size_t len);
+void iobuf_set_partial_body_length_mode (iobuf_t a, size_t len);
 
 /* If PARTIAL is set, then read from the pipeline until the first EOF
    is returned.