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