1 #ifndef _VSTREAM_H_INCLUDED_
2 #define _VSTREAM_H_INCLUDED_
3 
4 /*++
5 /* NAME
6 /*	vstream 3h
7 /* SUMMARY
8 /*	simple buffered I/O package
9 /* SYNOPSIS
10 /*	#include <vstream.h>
11 /* DESCRIPTION
12 /* .nf
13 
14  /*
15   * System library.
16   */
17 #include <sys/time.h>
18 #include <time.h>
19 #include <fcntl.h>
20 #include <stdarg.h>
21 #include <setjmp.h>
22 #include <unistd.h>
23 
24  /*
25   * Utility library.
26   */
27 #include <vbuf.h>
28 #include <check_arg.h>
29 
30  /*
31   * Simple buffered stream. The members of this structure are not part of the
32   * official interface and can change without prior notice.
33   */
34 typedef ssize_t (*VSTREAM_RW_FN) (int, void *, size_t, int, void *);
35 typedef pid_t(*VSTREAM_WAITPID_FN) (pid_t, WAIT_STATUS_T *, int);
36 
37 #ifdef NO_SIGSETJMP
38 #define VSTREAM_JMP_BUF	jmp_buf
39 #else
40 #define VSTREAM_JMP_BUF	sigjmp_buf
41 #endif
42 
43 typedef struct VSTREAM {
44     VBUF    buf;			/* generic intelligent buffer */
45     int     fd;				/* file handle, no 256 limit */
46     VSTREAM_RW_FN read_fn;		/* buffer fill action */
47     VSTREAM_RW_FN write_fn;		/* buffer flush action */
48     ssize_t req_bufsize;		/* requested read/write buffer size */
49     void   *context;			/* application context */
50     off_t   offset;			/* cached seek info */
51     char   *path;			/* give it at least try */
52     int     read_fd;			/* read channel (double-buffered) */
53     int     write_fd;			/* write channel (double-buffered) */
54     VBUF    read_buf;			/* read buffer (double-buffered) */
55     VBUF    write_buf;			/* write buffer (double-buffered) */
56     pid_t   pid;			/* vstream_popen/close() */
57     VSTREAM_WAITPID_FN waitpid_fn;	/* vstream_popen/close() */
58     int     timeout;			/* read/write timeout */
59     VSTREAM_JMP_BUF *jbuf;		/* exception handling */
60     struct timeval iotime;		/* time of last fill/flush */
61     struct timeval time_limit;		/* read/write time limit */
62     int     min_data_rate;		/* min data rate for time limit */
63     struct VSTRING *vstring;		/* memory-backed stream */
64 } VSTREAM;
65 
66 extern VSTREAM vstream_fstd[];		/* pre-defined streams */
67 
68 #define VSTREAM_IN		(&vstream_fstd[0])
69 #define VSTREAM_OUT		(&vstream_fstd[1])
70 #define VSTREAM_ERR		(&vstream_fstd[2])
71 
72 #define VSTREAM_FLAG_RD_ERR	VBUF_FLAG_RD_ERR	/* read error */
73 #define VSTREAM_FLAG_WR_ERR	VBUF_FLAG_WR_ERR	/* write error */
74 #define VSTREAM_FLAG_RD_TIMEOUT	VBUF_FLAG_RD_TIMEOUT	/* read timeout */
75 #define VSTREAM_FLAG_WR_TIMEOUT	VBUF_FLAG_WR_TIMEOUT	/* write timeout */
76 
77 #define	VSTREAM_FLAG_ERR	VBUF_FLAG_ERR	/* some I/O error */
78 #define VSTREAM_FLAG_EOF	VBUF_FLAG_EOF	/* end of file */
79 #define VSTREAM_FLAG_TIMEOUT	VBUF_FLAG_TIMEOUT	/* timeout error */
80 #define VSTREAM_FLAG_FIXED	VBUF_FLAG_FIXED	/* fixed-size buffer */
81 #define VSTREAM_FLAG_BAD	VBUF_FLAG_BAD
82 
83 /* Flags 1<<24 and above are reserved for VSTRING. */
84 #define VSTREAM_FLAG_READ	(1<<8)	/* read buffer */
85 #define VSTREAM_FLAG_WRITE	(1<<9)	/* write buffer */
86 #define VSTREAM_FLAG_SEEK	(1<<10)	/* seek info valid */
87 #define VSTREAM_FLAG_NSEEK	(1<<11)	/* can't seek this file */
88 #define VSTREAM_FLAG_DOUBLE	(1<<12)	/* double buffer */
89 #define VSTREAM_FLAG_DEADLINE	(1<<13)	/* deadline active */
90 #define VSTREAM_FLAG_MEMORY	(1<<14)	/* internal stream */
91 #define VSTREAM_FLAG_OWN_VSTRING (1<<15)/* owns VSTRING resource */
92 
93 #define VSTREAM_PURGE_READ	(1<<0)	/* flush unread data */
94 #define VSTREAM_PURGE_WRITE	(1<<1)	/* flush unwritten data */
95 #define VSTREAM_PURGE_BOTH	(VSTREAM_PURGE_READ|VSTREAM_PURGE_WRITE)
96 
97 #define VSTREAM_BUFSIZE		4096
98 
99 extern VSTREAM *vstream_fopen(const char *, int, mode_t);
100 extern int vstream_fclose(VSTREAM *);
101 extern off_t WARN_UNUSED_RESULT vstream_fseek(VSTREAM *, off_t, int);
102 extern off_t vstream_ftell(VSTREAM *);
103 extern int vstream_fpurge(VSTREAM *, int);
104 extern int vstream_fflush(VSTREAM *);
105 extern int vstream_fputs(const char *, VSTREAM *);
106 extern VSTREAM *vstream_fdopen(int, int);
107 extern int vstream_fdclose(VSTREAM *);
108 
109 #define vstream_fread(v, b, n)	vbuf_read(&(v)->buf, (b), (n))
110 #define vstream_fwrite(v, b, n)	vbuf_write(&(v)->buf, (b), (n))
111 
112 #define VSTREAM_PUTC(ch, vp)	VBUF_PUT(&(vp)->buf, (ch))
113 #define VSTREAM_GETC(vp)	VBUF_GET(&(vp)->buf)
114 #define vstream_ungetc(vp, ch)	vbuf_unget(&(vp)->buf, (ch))
115 #define VSTREAM_EOF		VBUF_EOF
116 
117 #define VSTREAM_PUTCHAR(ch)	VSTREAM_PUTC((ch), VSTREAM_OUT)
118 #define VSTREAM_GETCHAR()	VSTREAM_GETC(VSTREAM_IN)
119 
120 #define vstream_fileno(vp)	((vp)->fd)
121 #define vstream_req_bufsize(vp)	((const ssize_t) ((vp)->req_bufsize))
122 #define vstream_context(vp)	((vp)->context)
123 #define vstream_rd_error(vp)	vbuf_rd_error(&(vp)->buf)
124 #define vstream_wr_error(vp)	vbuf_wr_error(&(vp)->buf)
125 #define vstream_ferror(vp)	vbuf_error(&(vp)->buf)
126 #define vstream_feof(vp)	vbuf_eof(&(vp)->buf)
127 #define vstream_rd_timeout(vp)	vbuf_rd_timeout(&(vp)->buf)
128 #define vstream_wr_timeout(vp)	vbuf_wr_timeout(&(vp)->buf)
129 #define vstream_ftimeout(vp)	vbuf_timeout(&(vp)->buf)
130 #define vstream_clearerr(vp)	vbuf_clearerr(&(vp)->buf)
131 #define VSTREAM_PATH(vp)	((vp)->path ? (const char *) (vp)->path : "unknown_stream")
132 #define vstream_ftime(vp)	((time_t) ((vp)->iotime.tv_sec))
133 #define vstream_ftimeval(vp)	((vp)->iotime)
134 
135 #define vstream_fstat(vp, fl)	((vp)->buf.flags & (fl))
136 
137 extern ssize_t vstream_fread_buf(VSTREAM *, struct VSTRING *, ssize_t);
138 extern ssize_t vstream_fread_app(VSTREAM *, struct VSTRING *, ssize_t);
139 extern void vstream_control(VSTREAM *, int,...);
140 
141 /* Legacy API: type-unchecked arguments, internal use. */
142 #define VSTREAM_CTL_END		0
143 #define VSTREAM_CTL_READ_FN	1
144 #define VSTREAM_CTL_WRITE_FN	2
145 #define VSTREAM_CTL_PATH	3
146 #define VSTREAM_CTL_DOUBLE	4
147 #define VSTREAM_CTL_READ_FD	5
148 #define VSTREAM_CTL_WRITE_FD	6
149 #define VSTREAM_CTL_WAITPID_FN	7
150 #define VSTREAM_CTL_TIMEOUT	8
151 #define VSTREAM_CTL_EXCEPT	9
152 #define VSTREAM_CTL_CONTEXT	10
153 #ifdef F_DUPFD
154 #define VSTREAM_CTL_DUPFD	11
155 #endif
156 #define VSTREAM_CTL_BUFSIZE	12
157 #define VSTREAM_CTL_SWAP_FD	13
158 #define VSTREAM_CTL_START_DEADLINE 14
159 #define VSTREAM_CTL_STOP_DEADLINE 15
160 #define VSTREAM_CTL_OWN_VSTRING	16
161 #define VSTREAM_CTL_MIN_DATA_RATE 17
162 
163 /* Safer API: type-checked arguments, external use. */
164 #define CA_VSTREAM_CTL_END		VSTREAM_CTL_END
165 #define CA_VSTREAM_CTL_READ_FN(v)	VSTREAM_CTL_READ_FN, CHECK_VAL(VSTREAM_CTL, VSTREAM_RW_FN, (v))
166 #define CA_VSTREAM_CTL_WRITE_FN(v)	VSTREAM_CTL_WRITE_FN, CHECK_VAL(VSTREAM_CTL, VSTREAM_RW_FN, (v))
167 #define CA_VSTREAM_CTL_PATH(v)		VSTREAM_CTL_PATH, CHECK_CPTR(VSTREAM_CTL, char, (v))
168 #define CA_VSTREAM_CTL_DOUBLE		VSTREAM_CTL_DOUBLE
169 #define CA_VSTREAM_CTL_READ_FD(v)	VSTREAM_CTL_READ_FD, CHECK_VAL(VSTREAM_CTL, int, (v))
170 #define CA_VSTREAM_CTL_WRITE_FD(v)	VSTREAM_CTL_WRITE_FD, CHECK_VAL(VSTREAM_CTL, int, (v))
171 #define CA_VSTREAM_CTL_WAITPID_FN(v)	VSTREAM_CTL_WAITPID_FN, CHECK_VAL(VSTREAM_CTL, VSTREAM_WAITPID_FN, (v))
172 #define CA_VSTREAM_CTL_TIMEOUT(v)	VSTREAM_CTL_TIMEOUT, CHECK_VAL(VSTREAM_CTL, int, (v))
173 #define CA_VSTREAM_CTL_EXCEPT		VSTREAM_CTL_EXCEPT
174 #define CA_VSTREAM_CTL_CONTEXT(v)	VSTREAM_CTL_CONTEXT, CHECK_PTR(VSTREAM_CTL, void, (v))
175 #ifdef F_DUPFD
176 #define CA_VSTREAM_CTL_DUPFD(v)		VSTREAM_CTL_DUPFD, CHECK_VAL(VSTREAM_CTL, int, (v))
177 #endif
178 #define CA_VSTREAM_CTL_BUFSIZE(v)	VSTREAM_CTL_BUFSIZE, CHECK_VAL(VSTREAM_CTL, ssize_t, (v))
179 #define CA_VSTREAM_CTL_SWAP_FD(v)	VSTREAM_CTL_SWAP_FD, CHECK_PTR(VSTREAM_CTL, VSTREAM, (v))
180 #define CA_VSTREAM_CTL_START_DEADLINE	VSTREAM_CTL_START_DEADLINE
181 #define CA_VSTREAM_CTL_STOP_DEADLINE	VSTREAM_CTL_STOP_DEADLINE
182 #define CA_VSTREAM_CTL_MIN_DATA_RATE(v)	VSTREAM_CTL_MIN_DATA_RATE, CHECK_VAL(VSTREAM_CTL, int, (v))
183 
184 CHECK_VAL_HELPER_DCL(VSTREAM_CTL, ssize_t);
185 CHECK_VAL_HELPER_DCL(VSTREAM_CTL, int);
186 CHECK_VAL_HELPER_DCL(VSTREAM_CTL, VSTREAM_WAITPID_FN);
187 CHECK_VAL_HELPER_DCL(VSTREAM_CTL, VSTREAM_RW_FN);
188 CHECK_PTR_HELPER_DCL(VSTREAM_CTL, void);
189 CHECK_PTR_HELPER_DCL(VSTREAM_CTL, VSTREAM);
190 CHECK_CPTR_HELPER_DCL(VSTREAM_CTL, char);
191 
192 extern VSTREAM *PRINTFLIKE(1, 2) vstream_printf(const char *,...);
193 extern VSTREAM *PRINTFLIKE(2, 3) vstream_fprintf(VSTREAM *, const char *,...);
194 
195 extern VSTREAM *vstream_popen(int,...);
196 extern int vstream_pclose(VSTREAM *);
197 
198 #define vstream_ispipe(vp)	((vp)->pid != 0)
199 
200 /* Legacy API: type-unchecked arguments, internal use. */
201 #define VSTREAM_POPEN_END	0	/* terminator */
202 #define VSTREAM_POPEN_COMMAND	1	/* command is string */
203 #define VSTREAM_POPEN_ARGV	2	/* command is array */
204 #define VSTREAM_POPEN_UID	3	/* privileges */
205 #define VSTREAM_POPEN_GID	4	/* privileges */
206 #define VSTREAM_POPEN_ENV	5	/* extra environment */
207 #define VSTREAM_POPEN_SHELL	6	/* alternative shell */
208 #define VSTREAM_POPEN_WAITPID_FN 7	/* child catcher, waitpid() compat. */
209 #define VSTREAM_POPEN_EXPORT	8	/* exportable environment */
210 
211 /* Safer API: type-checked arguments, external use. */
212 #define CA_VSTREAM_POPEN_END		VSTREAM_POPEN_END
213 #define CA_VSTREAM_POPEN_COMMAND(v)	VSTREAM_POPEN_COMMAND, CHECK_CPTR(VSTREAM_PPN, char, (v))
214 #define CA_VSTREAM_POPEN_ARGV(v)	VSTREAM_POPEN_ARGV, CHECK_PPTR(VSTREAM_PPN, char, (v))
215 #define CA_VSTREAM_POPEN_UID(v)		VSTREAM_POPEN_UID, CHECK_VAL(VSTREAM_PPN, uid_t, (v))
216 #define CA_VSTREAM_POPEN_GID(v)		VSTREAM_POPEN_GID, CHECK_VAL(VSTREAM_PPN, gid_t, (v))
217 #define CA_VSTREAM_POPEN_ENV(v)		VSTREAM_POPEN_ENV, CHECK_PPTR(VSTREAM_PPN, char, (v))
218 #define CA_VSTREAM_POPEN_SHELL(v)	VSTREAM_POPEN_SHELL, CHECK_CPTR(VSTREAM_PPN, char, (v))
219 #define CA_VSTREAM_POPEN_WAITPID_FN(v)	VSTREAM_POPEN_WAITPID_FN, CHECK_VAL(VSTREAM_PPN, VSTREAM_WAITPID_FN, (v))
220 #define CA_VSTREAM_POPEN_EXPORT(v)	VSTREAM_POPEN_EXPORT, CHECK_PPTR(VSTREAM_PPN, char, (v))
221 
222 CHECK_VAL_HELPER_DCL(VSTREAM_PPN, uid_t);
223 CHECK_VAL_HELPER_DCL(VSTREAM_PPN, gid_t);
224 CHECK_VAL_HELPER_DCL(VSTREAM_PPN, VSTREAM_WAITPID_FN);
225 CHECK_PPTR_HELPER_DCL(VSTREAM_PPN, char);
226 CHECK_CPTR_HELPER_DCL(VSTREAM_PPN, char);
227 
228 extern VSTREAM *vstream_vprintf(const char *, va_list);
229 extern VSTREAM *vstream_vfprintf(VSTREAM *, const char *, va_list);
230 
231 extern ssize_t vstream_peek(VSTREAM *);
232 extern ssize_t vstream_bufstat(VSTREAM *, int);
233 
234 #define VSTREAM_BST_FLAG_IN		(1<<0)
235 #define VSTREAM_BST_FLAG_OUT		(1<<1)
236 #define VSTREAM_BST_FLAG_PEND		(1<<2)
237 
238 #define VSTREAM_BST_MASK_DIR	(VSTREAM_BST_FLAG_IN | VSTREAM_BST_FLAG_OUT)
239 #define VSTREAM_BST_IN_PEND	(VSTREAM_BST_FLAG_IN | VSTREAM_BST_FLAG_PEND)
240 #define VSTREAM_BST_OUT_PEND	(VSTREAM_BST_FLAG_OUT | VSTREAM_BST_FLAG_PEND)
241 
242 #define vstream_peek(vp) vstream_bufstat((vp), VSTREAM_BST_IN_PEND)
243 
244 extern const char *vstream_peek_data(VSTREAM *);
245 
246  /*
247   * Exception handling. We use pointer to jmp_buf to avoid a lot of unused
248   * baggage for streams that don't need this functionality.
249   *
250   * XXX sigsetjmp()/siglongjmp() save and restore the signal mask which can
251   * avoid surprises in code that manipulates signals, but unfortunately some
252   * systems have bugs in their implementation.
253   */
254 #ifdef NO_SIGSETJMP
255 #define vstream_setjmp(stream)		setjmp((stream)->jbuf[0])
256 #define vstream_longjmp(stream, val)	longjmp((stream)->jbuf[0], (val))
257 #else
258 #define vstream_setjmp(stream)		sigsetjmp((stream)->jbuf[0], 1)
259 #define vstream_longjmp(stream, val)	siglongjmp((stream)->jbuf[0], (val))
260 #endif
261 
262  /*
263   * Tweaks and workarounds.
264   */
265 extern int vstream_tweak_sock(VSTREAM *);
266 extern int vstream_tweak_tcp(VSTREAM *);
267 
268 #define vstream_flags(stream) ((const int) (stream)->buf.flags)
269 
270  /*
271   * Read/write VSTRING memory.
272   */
273 #define vstream_memopen(string, flags) \
274 	vstream_memreopen((VSTREAM *) 0, (string), (flags))
275 VSTREAM *vstream_memreopen(VSTREAM *, struct VSTRING *, int);
276 
277 /* LICENSE
278 /* .ad
279 /* .fi
280 /*	The Secure Mailer license must be distributed with this software.
281 /* AUTHOR(S)
282 /*	Wietse Venema
283 /*	IBM T.J. Watson Research
284 /*	P.O. Box 704
285 /*	Yorktown Heights, NY 10598, USA
286 /*
287 /*	Wietse Venema
288 /*	Google, Inc.
289 /*	111 8th Avenue
290 /*	New York, NY 10011, USA
291 /*--*/
292 
293 #endif
294