Silence two -Wlogical-op warnings.
[gnupg.git] / common / iobuf.h
index 7157e0f..22e02da 100644 (file)
@@ -25,7 +25,7 @@
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with this program; if not, see <http://www.gnu.org/licenses/>.
+ * along with this program; if not, see <https://www.gnu.org/licenses/>.
  */
 
 #ifndef GNUPG_COMMON_IOBUF_H
    in the iobuf_t.
 
    A pipeline can only be used for reading (IOBUF_INPUT) or for
-   writing (IOBUF_OUTPUT / IOBUF_TEMP).  When reading, data flows from
-   the last filter towards the first.  That is, the user calls
-   iobuf_read(), the module reads from the first filter, which gets
-   its input from the second filter, etc.  When writing, data flows
-   from the first filter towards the last.  In this case, when the
-   user calls iobuf_write(), the data is written to the first filter,
-   which writes the transformed data to the second filter, etc.
+   writing (IOBUF_OUTPUT / IOBUF_OUTPUT_TEMP).  When reading, data
+   flows from the last filter towards the first.  That is, the user
+   calls iobuf_read(), the module reads from the first filter, which
+   gets its input from the second filter, etc.  When writing, data
+   flows from the first filter towards the last.  In this case, when
+   the user calls iobuf_write(), the data is written to the first
+   filter, which writes the transformed data to the second filter,
+   etc.
 
    An iobuf_t contains some state about the filter.  For instance, it
    indicates if the filter has already returned EOF (filter_eof) and
@@ -118,20 +119,23 @@ typedef enum
     IOBUF_IOCTL_FSYNC            = 4  /* Uses ptrval.  */
   } iobuf_ioctl_t;
 
-enum
+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_TEMP=3
+    IOBUF_OUTPUT_TEMP
   };
 
 
@@ -142,8 +146,8 @@ typedef struct iobuf_struct *IOBUF;  /* Compatibility with gpg 1.4. */
 struct iobuf_struct
 {
   /* The type of filter.  Either IOBUF_INPUT, IOBUF_OUTPUT or
-     IOBUF_TEMP.  */
-  int use;
+     IOBUF_OUTPUT_TEMP.  */
+  enum iobuf_use use;
 
   /* nlimit can be changed using iobuf_set_limit.  If non-zero, it is
      the number of additional bytes that can be read from the filter
@@ -254,16 +258,10 @@ struct iobuf_struct
 #endif
 EXTERN_UNLESS_MAIN_MODULE int iobuf_debug_mode;
 
-/* Whether iobuf_open, iobuf_create and iobuf_is_pipefilename
-   recognize special filenames.  Special filenames are of the form
-   "-&nnnn" where n is a positive integer.  The integer corresponds to
-   a file descriptor.  Note: these functions always recognize the
-   special filename '-', which corresponds to standard input.  */
-void iobuf_enable_special_filenames (int yes);
 
 /* Returns whether the specified filename corresponds to a pipe.  In
    particular, this function checks if FNAME is "-" and, if special
-   filenames are enabled (see iobuf_enable_special_filenames), whether
+   filenames are enabled (see check_special_filename), whether
    FNAME is a special filename.  */
 int  iobuf_is_pipe_filename (const char *fname);
 
@@ -273,7 +271,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_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).  */
@@ -399,10 +398,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,
@@ -417,11 +415,18 @@ int iobuf_push_filter2 (iobuf_t a,
                                  byte * buf, size_t * len), void *ov,
                        int rel_ov);
 
+/* Pop the top filter.  The top filter must have the filter function F
+   and the cookie OV.  The cookie check is ignored if OV is NULL.  */
+int iobuf_pop_filter (iobuf_t a,
+                      int (*f) (void *opaque, int control,
+                                iobuf_t chain, byte * buf, size_t * len),
+                      void *ov);
+
 /* Used for debugging.  Prints out the chain using log_debug if
    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.  */
@@ -437,7 +442,7 @@ int iobuf_print_chain (iobuf_t a);
 void iobuf_set_limit (iobuf_t a, off_t nlimit);
 
 /* Returns the number of bytes that have been read from the pipeline.
-   Note: the result is undefined for IOBUF_OUTPUT and IOBUF_TEMP
+   Note: the result is undefined for IOBUF_OUTPUT and IOBUF_OUTPUT_TEMP
    pipelines!  */
 off_t iobuf_tell (iobuf_t a);
 
@@ -453,7 +458,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.
 
@@ -547,6 +552,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.
 
@@ -580,7 +593,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.
@@ -604,6 +617,6 @@ void iobuf_skip_rest (iobuf_t a, unsigned long n, int partial);
 #define iobuf_get_temp_length(a) ( (a)->d.len )
 
 /* Whether the filter uses an in-memory buffer.  */
-#define iobuf_is_temp(a)        ( (a)->use == IOBUF_TEMP )
+#define iobuf_is_temp(a)        ( (a)->use == IOBUF_OUTPUT_TEMP )
 
 #endif /*GNUPG_COMMON_IOBUF_H*/