PostgreSQL Source Code  git master
compress_io.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * compress_io.h
4  * Interface to compress_io.c routines
5  *
6  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  * IDENTIFICATION
10  * src/bin/pg_dump/compress_io.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 
15 #ifndef __COMPRESS_IO__
16 #define __COMPRESS_IO__
17 
18 #include "pg_backup_archiver.h"
19 
20 /*
21  * Default size used for IO buffers
22  *
23  * When changing this value, it's necessary to check the relevant test cases
24  * still exercise all the branches. This applies especially if the value is
25  * increased, in which case the overflow buffer may not be needed.
26  */
27 #define DEFAULT_IO_BUFFER_SIZE 4096
28 
29 extern char *supports_compression(const pg_compress_specification compression_spec);
30 
31 /*
32  * Prototype for callback function used in writeData()
33  */
34 typedef void (*WriteFunc) (ArchiveHandle *AH, const char *buf, size_t len);
35 
36 /*
37  * Prototype for callback function used in readData()
38  *
39  * readData will call the read function repeatedly, until it returns 0 to signal
40  * EOF. readData passes a buffer to read the data into in *buf, of length
41  * *buflen. If that's not big enough for the callback function, it can free() it
42  * and malloc() a new one, returning the new buffer and its size in *buf and
43  * *buflen.
44  *
45  * Returns the number of bytes read into *buf, or 0 on EOF.
46  */
47 typedef size_t (*ReadFunc) (ArchiveHandle *AH, char **buf, size_t *buflen);
48 
49 typedef struct CompressorState CompressorState;
51 {
52  /*
53  * Read all compressed data from the input stream (via readF) and print it
54  * out with ahwrite().
55  */
57 
58  /*
59  * Compress and write data to the output stream (via writeF).
60  */
62  const void *data, size_t dLen);
63 
64  /*
65  * End compression and flush internal buffers if any.
66  */
67  void (*end) (ArchiveHandle *AH, CompressorState *cs);
68 
69  /*
70  * Callback function to read from an already processed input stream
71  */
73 
74  /*
75  * Callback function to write an already processed chunk of data.
76  */
78 
79  /*
80  * Compression specification for this state.
81  */
83 
84  /*
85  * Private data to be used by the compressor.
86  */
87  void *private_data;
88 };
89 
90 extern CompressorState *AllocateCompressor(const pg_compress_specification compression_spec,
91  ReadFunc readF,
92  WriteFunc writeF);
94 
95 /*
96  * Compress File Handle
97  */
99 
101 {
102  /*
103  * Open a file in mode.
104  *
105  * Pass either 'path' or 'fd' depending on whether a file path or a file
106  * descriptor is available. 'mode' can be one of 'r', 'rb', 'w', 'wb',
107  * 'a', and 'ab'. Requires an already initialized CompressFileHandle.
108  *
109  * Returns true on success and false on error.
110  */
111  bool (*open_func) (const char *path, int fd, const char *mode,
112  CompressFileHandle *CFH);
113 
114  /*
115  * Open a file for writing.
116  *
117  * 'mode' can be one of 'w', 'wb', 'a', and 'ab'. Requires an already
118  * initialized CompressFileHandle.
119  *
120  * Returns true on success and false on error.
121  */
122  bool (*open_write_func) (const char *path, const char *mode,
123  CompressFileHandle *CFH);
124 
125  /*
126  * Read 'size' bytes of data from the file and store them into 'ptr'.
127  * Optionally it will store the number of bytes read in 'rsize'.
128  *
129  * Returns true on success and throws an internal error otherwise.
130  */
131  bool (*read_func) (void *ptr, size_t size, size_t *rsize,
132  CompressFileHandle *CFH);
133 
134  /*
135  * Write 'size' bytes of data into the file from 'ptr'.
136  *
137  * Returns true on success and false on error.
138  */
139  bool (*write_func) (const void *ptr, size_t size,
140  struct CompressFileHandle *CFH);
141 
142  /*
143  * Read at most size - 1 characters from the compress file handle into
144  * 's'.
145  *
146  * Stop if an EOF or a newline is found first. 's' is always null
147  * terminated and contains the newline if it was found.
148  *
149  * Returns 's' on success, and NULL on error or when end of file occurs
150  * while no characters have been read.
151  */
152  char *(*gets_func) (char *s, int size, CompressFileHandle *CFH);
153 
154  /*
155  * Read the next character from the compress file handle as 'unsigned
156  * char' cast into 'int'.
157  *
158  * Returns the character read on success and throws an internal error
159  * otherwise. It treats EOF as error.
160  */
162 
163  /*
164  * Test if EOF is reached in the compress file handle.
165  *
166  * Returns true if it is reached.
167  */
169 
170  /*
171  * Close an open file handle.
172  *
173  * Returns true on success and false on error.
174  */
176 
177  /*
178  * Get a pointer to a string that describes an error that occurred during
179  * a compress file handle operation.
180  */
181  const char *(*get_error_func) (CompressFileHandle *CFH);
182 
183  /*
184  * Compression specification for this file handle.
185  */
187 
188  /*
189  * Private data to be used by the compressor.
190  */
192 };
193 
194 /*
195  * Initialize a compress file handle with the requested compression.
196  */
198 
199 /*
200  * Initialize a compress file stream. Infer the compression algorithm
201  * from 'path', either by examining its suffix or by appending the supported
202  * suffixes in 'path'.
203  */
204 extern CompressFileHandle *InitDiscoverCompressFileHandle(const char *path,
205  const char *mode);
206 extern bool EndCompressFileHandle(CompressFileHandle *CFH);
207 #endif
unsigned char bool
Definition: c.h:459
size_t(* ReadFunc)(ArchiveHandle *AH, char **buf, size_t *buflen)
Definition: compress_io.h:47
bool EndCompressFileHandle(CompressFileHandle *CFH)
Definition: compress_io.c:289
char * supports_compression(const pg_compress_specification compression_spec)
Definition: compress_io.c:88
CompressorState * AllocateCompressor(const pg_compress_specification compression_spec, ReadFunc readF, WriteFunc writeF)
Definition: compress_io.c:124
void(* WriteFunc)(ArchiveHandle *AH, const char *buf, size_t len)
Definition: compress_io.h:34
void EndCompressor(ArchiveHandle *AH, CompressorState *cs)
Definition: compress_io.c:149
CompressFileHandle * InitDiscoverCompressFileHandle(const char *path, const char *mode)
Definition: compress_io.c:241
CompressFileHandle * InitCompressFileHandle(const pg_compress_specification compression_spec)
Definition: compress_io.c:195
static PgChecksumMode mode
Definition: pg_checksums.c:56
const void size_t len
const void * data
static char * buf
Definition: pg_test_fsync.c:73
static int fd(const char *x, int i)
Definition: preproc-init.c:105
static pg_noinline void Size size
Definition: slab.c:607
bool(* open_write_func)(const char *path, const char *mode, CompressFileHandle *CFH)
Definition: compress_io.h:122
bool(* write_func)(const void *ptr, size_t size, struct CompressFileHandle *CFH)
Definition: compress_io.h:139
int(* getc_func)(CompressFileHandle *CFH)
Definition: compress_io.h:161
bool(* eof_func)(CompressFileHandle *CFH)
Definition: compress_io.h:168
bool(* open_func)(const char *path, int fd, const char *mode, CompressFileHandle *CFH)
Definition: compress_io.h:111
pg_compress_specification compression_spec
Definition: compress_io.h:186
bool(* close_func)(CompressFileHandle *CFH)
Definition: compress_io.h:175
bool(* read_func)(void *ptr, size_t size, size_t *rsize, CompressFileHandle *CFH)
Definition: compress_io.h:131
void * private_data
Definition: compress_io.h:87
void(* readData)(ArchiveHandle *AH, CompressorState *cs)
Definition: compress_io.h:56
pg_compress_specification compression_spec
Definition: compress_io.h:82
void(* end)(ArchiveHandle *AH, CompressorState *cs)
Definition: compress_io.h:67
ReadFunc readF
Definition: compress_io.h:72
void(* writeData)(ArchiveHandle *AH, CompressorState *cs, const void *data, size_t dLen)
Definition: compress_io.h:61
WriteFunc writeF
Definition: compress_io.h:77