1 #ifndef _VSTRING_H_INCLUDED_
2 #define _VSTRING_H_INCLUDED_
3 
4 /*++
5 /* NAME
6 /*	vstring 3h
7 /* SUMMARY
8 /*	arbitrary-length string manager
9 /* SYNOPSIS
10 /*	#include "vstring.h"
11 /* DESCRIPTION
12 /* .nf
13 
14  /*
15   * System library.
16   */
17 #include <stdarg.h>
18 
19  /*
20   * Utility library.
21   */
22 #include <vbuf.h>
23 #include <check_arg.h>
24 
25  /*
26   * We can't allow bare VBUFs in the interface, because VSTRINGs have a
27   * specific initialization and destruction sequence.
28   */
29 typedef struct VSTRING {
30     VBUF    vbuf;
31 } VSTRING;
32 
33 extern VSTRING *vstring_alloc(ssize_t);
34 extern void vstring_ctl(VSTRING *,...);
35 extern VSTRING *vstring_truncate(VSTRING *, ssize_t);
36 extern VSTRING *vstring_set_payload_size(VSTRING *, ssize_t);
37 extern VSTRING *vstring_free(VSTRING *);
38 extern VSTRING *vstring_strcpy(VSTRING *, const char *);
39 extern VSTRING *vstring_strncpy(VSTRING *, const char *, ssize_t);
40 extern VSTRING *vstring_strcat(VSTRING *, const char *);
41 extern VSTRING *vstring_strncat(VSTRING *, const char *, ssize_t);
42 extern VSTRING *vstring_memcpy(VSTRING *, const char *, ssize_t);
43 extern VSTRING *vstring_memcat(VSTRING *, const char *, ssize_t);
44 extern char *vstring_memchr(VSTRING *, int);
45 extern VSTRING *vstring_insert(VSTRING *, ssize_t, const char *, ssize_t);
46 extern VSTRING *vstring_prepend(VSTRING *, const char *, ssize_t);
47 extern VSTRING *PRINTFLIKE(2, 3) vstring_sprintf(VSTRING *, const char *,...);
48 extern VSTRING *PRINTFLIKE(2, 3) vstring_sprintf_append(VSTRING *, const char *,...);
49 extern VSTRING *PRINTFLIKE(2, 3) vstring_sprintf_prepend(VSTRING *, const char *,...);
50 extern char *vstring_export(VSTRING *);
51 extern VSTRING *vstring_import(char *);
52 
53 /* Legacy API: constant plus type-unchecked argument. */
54 #define VSTRING_CTL_EXACT	2
55 #define VSTRING_CTL_END		0
56 
57 /* Safer API: type-checked arguments. */
58 #define CA_VSTRING_CTL_END		VSTRING_CTL_END
59 #define CA_VSTRING_CTL_EXACT		VSTRING_CTL_EXACT
60 
61 CHECK_VAL_HELPER_DCL(VSTRING_CTL, ssize_t);
62 
63 /* Flags 24..31 are reserved for VSTRING. */
64 #define VSTRING_FLAG_EXACT	(1<<24)	/* exact allocation for tests */
65 #define VSTRING_FLAG_MASK	(255 << 24)
66 
67  /*
68   * Macros. Unsafe macros have UPPERCASE names.
69   */
70 #define VSTRING_SPACE(vp, len)	((vp)->vbuf.space(&(vp)->vbuf, (len)))
71 #define vstring_str(vp)		((char *) (vp)->vbuf.data)
72 #define VSTRING_LEN(vp)		((ssize_t) ((vp)->vbuf.ptr - (vp)->vbuf.data))
73 #define vstring_end(vp)		((char *) (vp)->vbuf.ptr)
74 #define VSTRING_TERMINATE(vp)	do { \
75 				    *(vp)->vbuf.ptr = 0; \
76 				} while (0)
77 #define VSTRING_RESET(vp)	do { \
78 				    (vp)->vbuf.ptr = (vp)->vbuf.data; \
79 				    (vp)->vbuf.cnt = (vp)->vbuf.len; \
80 				} while (0)
81 #define	VSTRING_ADDCH(vp, ch)	VBUF_PUT(&(vp)->vbuf, ch)
82 #define VSTRING_SKIP(vp)	do { \
83 				    while ((vp)->vbuf.cnt > 0 && *(vp)->vbuf.ptr) \
84 				        (vp)->vbuf.ptr++, (vp)->vbuf.cnt--; \
85 				} while (0)
86 #define vstring_avail(vp)	((vp)->vbuf.cnt)
87 
88  /*
89   * The following macro is not part of the public interface, because it can
90   * really screw up a buffer by positioning past allocated memory.
91   */
92 #ifdef VSTRING_INTERNAL
93 #define VSTRING_AT_OFFSET(vp, offset) do { \
94 	(vp)->vbuf.ptr = (vp)->vbuf.data + (offset); \
95 	(vp)->vbuf.cnt = (vp)->vbuf.len - (offset); \
96     } while (0)
97 #endif
98 
99 extern VSTRING *vstring_vsprintf(VSTRING *, const char *, va_list);
100 extern VSTRING *vstring_vsprintf_append(VSTRING *, const char *, va_list);
101 
102 /* BUGS
103 /*	Auto-resizing may change the address of the string data in
104 /*	a vstring structure. Beware of dangling pointers.
105 /* HISTORY
106 /* .ad
107 /* .fi
108 /*	A vstring module appears in the UNPROTO software by Wietse Venema.
109 /* LICENSE
110 /* .ad
111 /* .fi
112 /*	The Secure Mailer license must be distributed with this software.
113 /* AUTHOR(S)
114 /*	Wietse Venema
115 /*	IBM T.J. Watson Research
116 /*	P.O. Box 704
117 /*	Yorktown Heights, NY 10598, USA
118 /*
119 /*	Wietse Venema
120 /*	Google, Inc.
121 /*	111 8th Avenue
122 /*	New York, NY 10011, USA
123 /*--*/
124 
125 #endif
126