


vstr(3)                Vstr String Library                vstr(3)


SYNOPSIS
  #include <vstr.h>


  int vstr_init(void);
  void vstr_exit(void);

  const char *vstr_export_cstr_ptr(const struct Vstr_base *, size_t, size_t);
  char *vstr_export_cstr_malloc(const struct Vstr_base *, size_t, size_t);
  void  vstr_export_cstr_buf(const struct Vstr_base *, size_t, size_t, void *,
                            size_t);
  struct Vstr_ref  *vstr_export_cstr_ref(const  struct  Vstr_base  *,  size_t,
                                        size_t, size_t *);
  size_t  vstr_export_iovec_ptr_all(const struct Vstr_base *, struct iovec **,
                                   unsigned int *);
  size_t vstr_export_iovec_cpy_buf(const struct Vstr_base *,  size_t,  size_t,
                                   struct  iovec *, unsigned int, unsigned int
                                   *);
  size_t vstr_export_iovec_cpy_ptr(const struct Vstr_base *,  size_t,  size_t,
                                   struct  iovec *, unsigned int, unsigned int
                                   *);
  size_t vstr_export_buf(const struct Vstr_base *,  size_t,  size_t,  void  *,
                         size_t);
  char vstr_export_chr(const struct Vstr_base *, size_t);
  struct  Vstr_ref  *vstr_export_ref(const struct Vstr_base *, size_t, size_t,
                                   size_t *);

  struct Vstr_ref *vstr_ref_add(struct Vstr_ref *);
  void vstr_ref_del(struct Vstr_ref *);
  void vstr_ref_cb_free_nothing(struct Vstr_ref *);
  void vstr_ref_cb_free_ref(struct Vstr_ref *);
  void vstr_ref_cb_free_ptr(struct Vstr_ref *);
  void vstr_ref_cb_free_ptr_ref(struct Vstr_ref *);
  struct Vstr_ref *vstr_ref_make_malloc(size_t);
  struct Vstr_ref *vstr_ref_make_ptr(void *, void (*)(struct Vstr_ref *));
  struct Vstr_ref *vstr_ref_make_memdup(void *, size_t);
  struct Vstr_ref *vstr_ref_make_strdup(char *);
  struct Vstr_ref *VSTR_REF_MAKE_STRDUP(char *);
  struct Vstr_ref *vstr_ref_make_vstr_base(struct Vstr_base *);
  struct Vstr_ref *vstr_ref_make_vstr_conf(struct Vstr_conf *);
  struct Vstr_ref *vstr_ref_make_vstr_sects(struct Vstr_sects *);

  struct Vstr_conf *vstr_make_conf(void);
  void vstr_free_conf(struct Vstr_conf *);
  struct Vstr_base *vstr_make_base(struct Vstr_conf *);
  void vstr_free_base(struct Vstr_base *);
  struct Vstr_base *vstr_dup_buf(struct Vstr_conf *, const void *, size_t);
  struct Vstr_base *vstr_dup_ptr(struct Vstr_conf *, const void *, size_t);
  struct Vstr_base *vstr_dup_non(struct Vstr_conf *, size_t);
  struct  Vstr_base  *vstr_dup_ref(struct  Vstr_conf  *,  struct  Vstr_ref  *,
                                 size_t, size_t);
  struct  Vstr_base  *vstr_dup_vstr(struct Vstr_conf *, const struct Vstr_base
                                  *, size_t, size_t, unsigned int);
  struct Vstr_base *vstr_dup_rep_chr(struct Vstr_conf *, char, size_t);



Vstr 1.0.15                06-Mar-2006                          1





vstr(3)                Vstr String Library                vstr(3)


  struct Vstr_base *vstr_dup_cstr_buf(struct Vstr_conf *, const char *);
  struct Vstr_base *vstr_dup_cstr_ptr(struct Vstr_conf *, const char *);
  int vstr_dup_cstr_ref(struct Vstr_base *, struct Vstr_ref *, size_t);
  struct Vstr_base *VSTR_DUP_CSTR_BUF(struct Vstr_conf *, const char *);
  struct Vstr_base *VSTR_DUP_CSTR_PTR(struct Vstr_conf *, const char *);
  int VSTR_DUP_CSTR_REF(struct Vstr_base *, struct Vstr_ref *, size_t);
  unsigned  int  vstr_make_spare_nodes(struct  Vstr_conf  *,   unsigned   int,
                                     unsigned int);
  unsigned   int   vstr_free_spare_nodes(struct  Vstr_conf  *,  unsigned  int,
                                     unsigned int);

  int vstr_add_buf(struct Vstr_base *, size_t, const void *, size_t);
  int vstr_add_ptr(struct Vstr_base *, size_t, const void *, size_t);
  int vstr_add_non(struct Vstr_base *, size_t, size_t);
  int vstr_add_ref(const  struct  Vstr_base  *,  size_t,  struct  Vstr_ref  *,
                   size_t, size_t);
  int  vstr_add_vstr(const  struct Vstr_base *, size_t, const struct Vstr_base
                    *, size_t, size_t, unsigned int);
  int vstr_add_rep_chr(struct Vstr_base *, size_t, char, size_t);
  int vstr_add_cstr_buf(struct Vstr_base *, size_t, const char *);
  int vstr_add_cstr_ptr(struct Vstr_base *, size_t, const char *);
  int  vstr_add_cstr_ref(struct  Vstr_base  *,  size_t,  struct  Vstr_ref   *,
                        size_t);
  int VSTR_ADD_CSTR_BUF(struct Vstr_base *, size_t, const char *);
  int VSTR_ADD_CSTR_PTR(struct Vstr_base *, size_t, const char *);
  int   VSTR_ADD_CSTR_REF(struct  Vstr_base  *,  size_t,  struct  Vstr_ref  *,
                        size_t);
  size_t vstr_add_vfmt(struct Vstr_base *, size_t, const char *, va_list);
  size_t vstr_add_fmt(struct Vstr_base *, size_t, const char *, ...);
  size_t vstr_add_vsysfmt(struct Vstr_base *, size_t, const char *, va_list);
  size_t vstr_add_sysfmt(struct Vstr_base *, size_t, const char *, ...);
  size_t vstr_add_iovec_buf_beg(struct  Vstr_base  *,  size_t,  unsigned  int,
                                unsigned  int,  struct  iovec **, unsigned int
                                *);
  void vstr_add_iovec_buf_end(const struct Vstr_base *, size_t, size_t);
  size_t vstr_add_netstr_beg(struct Vstr_base *, size_t);
  int vstr_add_netstr_end(struct Vstr_base *, size_t, size_t);
  size_t vstr_add_netstr2_beg(struct Vstr_base *, size_t);
  int vstr_add_netstr2_end(struct Vstr_base *, size_t, size_t);
  int vstr_del(struct Vstr_base *, size_t, size_t);
  int  vstr_mov(struct  Vstr_base  *,  size_t,  struct  Vstr_base  *,  size_t,
               size_t);

  int vstr_sub_buf(struct Vstr_base *, size_t, size_t, const void *, size_t);
  int vstr_sub_ptr(struct Vstr_base *, size_t, size_t, const void *, size_t);
  int vstr_sub_non(struct Vstr_base *, size_t, size_t, size_t);
  int  vstr_sub_ref(struct  Vstr_base  *,  size_t,  size_t, struct Vstr_ref *,
                   size_t, size_t);
  int vstr_sub_vstr(struct Vstr_base *, size_t, size_t, const struct Vstr_base
                    *, size_t, size_t, unsigned int);
  int vstr_sub_rep_chr(struct Vstr_base *, size_t, size_t, char, size_t);
  int vstr_sub_cstr_buf(struct Vstr_base *, size_t, size_t, const char *);
  int vstr_sub_cstr_ptr(struct Vstr_base *, size_t, size_t, const char *);
  int vstr_sub_cstr_ref(struct Vstr_base *, size_t, size_t, struct Vstr_ref *,



Vstr 1.0.15                06-Mar-2006                          2





vstr(3)                Vstr String Library                vstr(3)


                        size_t);
  int VSTR_SUB_CSTR_BUF(struct Vstr_base *, size_t, size_t, const char *);
  int VSTR_SUB_CSTR_PTR(struct Vstr_base *, size_t, size_t, const char *);
  int VSTR_SUB_CSTR_REF(struct Vstr_base *, size_t, size_t, struct Vstr_ref *,
                        size_t);

  int   vstr_cmp(const  struct  Vstr_base  *,  size_t,  size_t,  const  struct
               Vstr_base *, size_t, size_t);
  int vstr_cmp_buf(const struct Vstr_base *, size_t,  size_t,  const  void  *,
                   size_t);
  int  vstr_cmp_case(const  struct  Vstr_base  *, size_t, size_t, const struct
                    Vstr_base *, size_t, size_t);
  int vstr_cmp_case_buf(const struct Vstr_base *, size_t, size_t,  const  char
                        *, size_t);
  int  vstr_cmp_fast(const  struct  Vstr_base  *, size_t, size_t, const struct
                    Vstr_base *, size_t, size_t);
  int vstr_cmp_fast_buf(const struct Vstr_base *, size_t, size_t,  const  char
                        *, size_t);
  int  vstr_cmp_vers(const  struct  Vstr_base  *, size_t, size_t, const struct
                    Vstr_base *, size_t, size_t);
  int vstr_cmp_vers_buf(const struct Vstr_base *, size_t, size_t,  const  char
                        *, size_t);
  int  vstr_cmp_eq(const  struct  Vstr_base  *,  size_t,  size_t, const struct
                  Vstr_base *, size_t, size_t);
  int vstr_cmp_cstr(const struct Vstr_base *, size_t, size_t, const char *);
  int vstr_cmp_buf_eq(const struct Vstr_base *, size_t, size_t, const void  *,
                      size_t);
  int  vstr_cmp_cstr_eq(const  struct  Vstr_base *, size_t, size_t, const char
                       *);
  int vstr_cmp_case_eq(const struct Vstr_base *, size_t, size_t, const  struct
                       Vstr_base *, size_t, size_t);
  int  vstr_cmp_case_cstr(const struct Vstr_base *, size_t, size_t, const char
                         *);
  int vstr_cmp_case_buf_eq(const struct Vstr_base  *,  size_t,  size_t,  const
                           void *, size_t);
  int  vstr_cmp_case_cstr_eq(const  struct  Vstr_base *, size_t, size_t, const
                            char *);
  int vstr_cmp_fast_cstr(const struct Vstr_base *, size_t, size_t, const  char
                         *);
  int  vstr_cmp_vers_eq(const struct Vstr_base *, size_t, size_t, const struct
                       Vstr_base *, size_t, size_t);
  int vstr_cmp_vers_cstr(const struct Vstr_base *, size_t, size_t, const  char
                         *);
  int  vstr_cmp_vers_buf_eq(const  struct  Vstr_base  *, size_t, size_t, const
                           void *, size_t);
  int vstr_cmp_vers_cstr_eq(const struct Vstr_base *,  size_t,  size_t,  const
                            char *);
  int  vstr_cmp_bod(const  struct  Vstr_base  *,  size_t, size_t, const struct
                   Vstr_base *, size_t, size_t);
  int vstr_cmp_eod(const struct Vstr_base  *,  size_t,  size_t,  const  struct
                   Vstr_base *, size_t, size_t);
  int  vstr_cmp_bod_eq(const  struct Vstr_base *, size_t, size_t, const struct
                      Vstr_base *, size_t, size_t);
  int vstr_cmp_eod_eq(const struct Vstr_base *, size_t, size_t,  const  struct



Vstr 1.0.15                06-Mar-2006                          3





vstr(3)                Vstr String Library                vstr(3)


                      Vstr_base *, size_t, size_t);
  int vstr_cmp_bod_buf(const struct Vstr_base *, size_t, size_t, const void *,
                       size_t);
  int vstr_cmp_eod_buf(const struct Vstr_base *, size_t, size_t, const void *,
                       size_t);
  int vstr_cmp_bod_buf_eq(const struct Vstr_base *, size_t, size_t, const void
                          *, size_t);
  int vstr_cmp_eod_buf_eq(const struct Vstr_base *, size_t, size_t, const void
                          *, size_t);
  int  vstr_cmp_bod_cstr(const  struct Vstr_base *, size_t, size_t, const char
                        *);
  int vstr_cmp_eod_cstr(const struct Vstr_base *, size_t, size_t,  const  char
                        *);
  int  vstr_cmp_bod_cstr_eq(const  struct  Vstr_base  *, size_t, size_t, const
                           char *);
  int vstr_cmp_eod_cstr_eq(const struct Vstr_base  *,  size_t,  size_t,  const
                           char *);
  int vstr_cmp_case_bod(const struct Vstr_base *, size_t, size_t, const struct
                        Vstr_base *, size_t, size_t);
  int vstr_cmp_case_eod(const struct Vstr_base *, size_t, size_t, const struct
                        Vstr_base *, size_t, size_t);
  int  vstr_cmp_case_bod_eq(const  struct  Vstr_base  *, size_t, size_t, const
                           struct Vstr_base *, size_t, size_t);
  int vstr_cmp_case_eod_eq(const struct Vstr_base  *,  size_t,  size_t,  const
                           struct Vstr_base *, size_t, size_t);
  int  vstr_cmp_case_bod_buf(const  struct  Vstr_base *, size_t, size_t, const
                            char *, size_t);
  int vstr_cmp_case_eod_buf(const struct Vstr_base *,  size_t,  size_t,  const
                            char *, size_t);
  int vstr_cmp_case_bod_buf_eq(const struct Vstr_base *, size_t, size_t, const
                               char *, size_t);
  int vstr_cmp_case_eod_buf_eq(const struct Vstr_base *, size_t, size_t, const
                               char *, size_t);
  int  vstr_cmp_case_bod_cstr(const  struct Vstr_base *, size_t, size_t, const
                             char *);
  int vstr_cmp_case_eod_cstr(const struct Vstr_base *, size_t,  size_t,  const
                             char *);
  int  vstr_cmp_case_bod_cstr_eq(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  int vstr_cmp_case_eod_cstr_eq(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  int vstr_cmp_vers_bod(const struct Vstr_base *, size_t, size_t, const struct
                        Vstr_base *, size_t, size_t);
  int vstr_cmp_vers_eod(const struct Vstr_base *, size_t, size_t, const struct
                        Vstr_base *, size_t, size_t);
  int  vstr_cmp_vers_bod_eq(const  struct  Vstr_base  *, size_t, size_t, const
                           struct Vstr_base *, size_t, size_t);
  int vstr_cmp_vers_eod_eq(const struct Vstr_base  *,  size_t,  size_t,  const
                           struct Vstr_base *, size_t, size_t);
  int  vstr_cmp_vers_bod_buf(const  struct  Vstr_base *, size_t, size_t, const
                            char *, size_t);
  int vstr_cmp_vers_eod_buf(const struct Vstr_base *,  size_t,  size_t,  const
                            char *, size_t);
  int vstr_cmp_vers_bod_buf_eq(const struct Vstr_base *, size_t, size_t, const



Vstr 1.0.15                06-Mar-2006                          4





vstr(3)                Vstr String Library                vstr(3)


                               char *, size_t);
  int vstr_cmp_vers_eod_buf_eq(const struct Vstr_base *, size_t, size_t, const
                               char *, size_t);
  int  vstr_cmp_vers_bod_cstr(const  struct Vstr_base *, size_t, size_t, const
                             char *);
  int vstr_cmp_vers_eod_cstr(const struct Vstr_base *, size_t,  size_t,  const
                             char *);
  int  vstr_cmp_vers_bod_cstr_eq(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  int vstr_cmp_vers_eod_cstr_eq(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  int  VSTR_CMP_EQ(const  struct  Vstr_base  *,  size_t,  size_t, const struct
                  Vstr_base *, size_t, size_t);
  int VSTR_CMP_CSTR(const struct Vstr_base *, size_t, size_t, const char *);
  int VSTR_CMP_BUF_EQ(const struct Vstr_base *, size_t, size_t, const void  *,
                      size_t);
  int  VSTR_CMP_CSTR_EQ(const  struct  Vstr_base *, size_t, size_t, const char
                       *);
  int VSTR_CMP_CASE_EQ(const struct Vstr_base *, size_t, size_t, const  struct
                       Vstr_base *, size_t, size_t);
  int  VSTR_CMP_CASE_CSTR(const struct Vstr_base *, size_t, size_t, const char
                         *);
  int VSTR_CMP_CASE_BUF_EQ(const struct Vstr_base  *,  size_t,  size_t,  const
                           void *, size_t);
  int  VSTR_CMP_CASE_CSTR_EQ(const  struct  Vstr_base *, size_t, size_t, const
                            char *);
  int VSTR_CMP_VERS_EQ(const struct Vstr_base *, size_t, size_t, const  struct
                       Vstr_base *, size_t, size_t);
  int  VSTR_CMP_VERS_CSTR(const struct Vstr_base *, size_t, size_t, const char
                         *);
  int VSTR_CMP_VERS_BUF_EQ(const struct Vstr_base  *,  size_t,  size_t,  const
                           void *, size_t);
  int  VSTR_CMP_VERS_CSTR_EQ(const  struct  Vstr_base *, size_t, size_t, const
                            char *);

  size_t vstr_srch_chr_fwd(const struct Vstr_base *, size_t, size_t, char);
  size_t vstr_srch_chr_rev(const struct Vstr_base *, size_t, size_t, char);
  size_t vstr_srch_chrs_fwd(const struct Vstr_base *,  size_t,  size_t,  const
                            char *, size_t);
  size_t  vstr_srch_chrs_rev(const  struct  Vstr_base *, size_t, size_t, const
                            char *, size_t);
  size_t vstr_csrch_chrs_fwd(const struct Vstr_base *, size_t,  size_t,  const
                             char *, size_t);
  size_t  vstr_csrch_chrs_rev(const  struct Vstr_base *, size_t, size_t, const
                             char *, size_t);
  size_t vstr_srch_buf_fwd(const struct Vstr_base  *,  size_t,  size_t,  const
                           void *, size_t);
  size_t  vstr_srch_buf_rev(const  struct  Vstr_base  *, size_t, size_t, const
                           void *, size_t);
  size_t vstr_srch_vstr_fwd(const struct Vstr_base *,  size_t,  size_t,  const
                            struct Vstr_base *, size_t, size_t);
  size_t  vstr_srch_vstr_rev(const  struct  Vstr_base *, size_t, size_t, const
                            struct Vstr_base *, size_t, size_t);
  size_t vstr_srch_case_chr_fwd(const  struct  Vstr_base  *,  size_t,  size_t,



Vstr 1.0.15                06-Mar-2006                          5





vstr(3)                Vstr String Library                vstr(3)


                                char);
  size_t  vstr_srch_case_chr_rev(const  struct  Vstr_base  *,  size_t, size_t,
                                char);
  size_t vstr_srch_case_buf_fwd(const  struct  Vstr_base  *,  size_t,  size_t,
                                const void *, size_t);
  size_t  vstr_srch_case_buf_rev(const  struct  Vstr_base  *,  size_t, size_t,
                                const void *, size_t);
  size_t vstr_srch_case_vstr_fwd(const struct  Vstr_base  *,  size_t,  size_t,
                                 const struct Vstr_base *, size_t, size_t);
  size_t  vstr_srch_case_vstr_rev(const  struct  Vstr_base  *, size_t, size_t,
                                 const struct Vstr_base *, size_t, size_t);
  size_t vstr_srch_cstr_buf_fwd(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  size_t  vstr_srch_cstr_buf_rev(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  size_t vstr_srch_cstr_chrs_fwd(const struct  Vstr_base  *,  size_t,  size_t,
                                 const char *);
  size_t  vstr_srch_cstr_chrs_rev(const  struct  Vstr_base  *, size_t, size_t,
                                 const char *);
  size_t vstr_csrch_cstr_chrs_fwd(const struct Vstr_base  *,  size_t,  size_t,
                                  const char *);
  size_t  vstr_csrch_cstr_chrs_rev(const  struct  Vstr_base *, size_t, size_t,
                                  const char *);
  size_t vstr_srch_case_cstr_buf_fwd(const struct Vstr_base *, size_t, size_t,
                                     const char *);
  size_t vstr_srch_case_cstr_buf_rev(const struct Vstr_base *, size_t, size_t,
                                     const char *);
  size_t VSTR_SRCH_CSTR_BUF_FWD(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  size_t  VSTR_SRCH_CSTR_BUF_REV(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  size_t VSTR_SRCH_CSTR_CHRS_FWD(const struct  Vstr_base  *,  size_t,  size_t,
                                 const char *);
  size_t  VSTR_SRCH_CSTR_CHRS_REV(const  struct  Vstr_base  *, size_t, size_t,
                                 const char *);
  size_t VSTR_CSRCH_CSTR_CHRS_FWD(const struct Vstr_base  *,  size_t,  size_t,
                                  const char *);
  size_t  VSTR_CSRCH_CSTR_CHRS_REV(const  struct  Vstr_base *, size_t, size_t,
                                  const char *);
  size_t VSTR_SRCH_CASE_CSTR_BUF_FWD(const struct Vstr_base *, size_t, size_t,
                                     const char *);
  size_t VSTR_SRCH_CASE_CSTR_BUF_REV(const struct Vstr_base *, size_t, size_t,
                                     const char *);

  size_t vstr_spn_bmap_eq_fwd(const struct Vstr_base *, size_t, size_t,  const
                              unsigned char[256], unsigned char);
  size_t  vstr_spn_bmap_eq_rev(const struct Vstr_base *, size_t, size_t, const
                              unsigned char[256], unsigned char);
  size_t vstr_spn_bmap_and_fwd(const struct Vstr_base *, size_t, size_t, const
                               unsigned char[256], unsigned char);
  size_t vstr_spn_bmap_and_rev(const struct Vstr_base *, size_t, size_t, const
                               unsigned char[256], unsigned char);
  size_t vstr_spn_chrs_fwd(const struct Vstr_base  *,  size_t,  size_t,  const
                           char *, size_t);



Vstr 1.0.15                06-Mar-2006                          6





vstr(3)                Vstr String Library                vstr(3)


  size_t  vstr_spn_chrs_rev(const  struct  Vstr_base  *, size_t, size_t, const
                           char *, size_t);
  size_t vstr_cspn_bmap_eq_fwd(const struct Vstr_base *, size_t, size_t, const
                               unsigned char[256], unsigned char);
  size_t vstr_cspn_bmap_eq_rev(const struct Vstr_base *, size_t, size_t, const
                               unsigned char[256], unsigned char);
  size_t vstr_cspn_bmap_and_fwd(const  struct  Vstr_base  *,  size_t,  size_t,
                                const unsigned char[256], unsigned char);
  size_t  vstr_cspn_bmap_and_rev(const  struct  Vstr_base  *,  size_t, size_t,
                                const unsigned char[256], unsigned char);
  size_t vstr_cspn_chrs_fwd(const struct Vstr_base *,  size_t,  size_t,  const
                            char *, size_t);
  size_t  vstr_cspn_chrs_rev(const  struct  Vstr_base *, size_t, size_t, const
                            char *, size_t);
  size_t vstr_spn_cstr_chrs_fwd(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  size_t  vstr_spn_cstr_chrs_rev(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  size_t vstr_cspn_cstr_chrs_fwd(const struct  Vstr_base  *,  size_t,  size_t,
                                 const char *);
  size_t  vstr_cspn_cstr_chrs_rev(const  struct  Vstr_base  *, size_t, size_t,
                                 const char *);
  size_t VSTR_SPN_CSTR_CHRS_FWD(const  struct  Vstr_base  *,  size_t,  size_t,
                                const char *);
  size_t  VSTR_SPN_CSTR_CHRS_REV(const  struct  Vstr_base  *,  size_t, size_t,
                                const char *);
  size_t VSTR_CSPN_CSTR_CHRS_FWD(const struct  Vstr_base  *,  size_t,  size_t,
                                 const char *);
  size_t  VSTR_CSPN_CSTR_CHRS_REV(const  struct  Vstr_base  *, size_t, size_t,
                                 const char *);

  int vstr_conv_lowercase(struct Vstr_base *, size_t, size_t);
  int vstr_conv_uppercase(struct Vstr_base *, size_t, size_t);
  int vstr_conv_unprintable_chr(const  struct  Vstr_base  *,  size_t,  size_t,
                                unsigned int, char);
  int  vstr_conv_unprintable_del(const  struct  Vstr_base  *,  size_t, size_t,
                                unsigned int);
  int vstr_conv_encode_uri(const struct Vstr_base *, size_t, size_t);
  int vstr_conv_decode_uri(const struct Vstr_base *, size_t, size_t);

  struct Vstr_sects *VSTR_SECTS_DECL(<symbol>, unsigned int);
  struct Vstr_sects *VSTR_SECTS_EXTERN_DECL(<symbol>, unsigned int);
  void VSTR_SECTS_DECL_INIT(struct Vstr_sects *);
  void   VSTR_SECTS_INIT(struct   Vstr_sects   *,   unsigned    int,    struct
                       Vstr_sect_node *, int);
  struct Vstr_sect_node *VSTR_SECTS_NUM(struct Vstr_sects *, unsigned int);
  struct Vstr_sects *vstr_sects_make(unsigned int);
  void vstr_sects_free(struct Vstr_sects *);
  int vstr_sects_add(struct Vstr_sects *, size_t, size_t);
  int vstr_sects_del(struct Vstr_sects *, unsigned int);
  unsigned  int vstr_sects_foreach(const struct Vstr_base *, struct Vstr_sects
                                  *,  unsigned  int,  unsigned  int  (*)(const
                                  Vstr_base  *,  size_t, size_t, void *), void
                                  *);



Vstr 1.0.15                06-Mar-2006                          7





vstr(3)                Vstr String Library                vstr(3)


  int vstr_sects_update_add(const struct Vstr_base *, struct Vstr_sects *);
  int vstr_sects_update_del(const struct Vstr_base *, struct Vstr_sects *);
  unsigned int vstr_sects_srch(struct Vstr_sects *, size_t, size_t);

  unsigned int vstr_split_buf(const struct Vstr_base *, size_t, size_t,  const
                              void  *,  size_t,  struct Vstr_sects *, unsigned
                              int, unsigned int);
  unsigned int vstr_split_chrs(const struct Vstr_base *, size_t, size_t, const
                               char  *,  size_t, struct Vstr_sects *, unsigned
                               int, unsigned int);
  unsigned int vstr_split_cstr_buf(const struct Vstr_base *,  size_t,  size_t,
                                   const char *, struct Vstr_sects *, unsigned
                                   int, unsigned int);
  unsigned int vstr_split_cstr_chrs(const struct Vstr_base *, size_t,  size_t,
                                    const   char   *,   struct  Vstr_sects  *,
                                    unsigned int, unsigned int);
  unsigned int VSTR_SPLIT_CSTR_BUF(const struct Vstr_base *,  size_t,  size_t,
                                   const char *, struct Vstr_sects *, unsigned
                                   int, unsigned int);
  unsigned int VSTR_SPLIT_CSTR_CHRS(const struct Vstr_base *, size_t,  size_t,
                                    const   char   *,   struct  Vstr_sects  *,
                                    unsigned int, unsigned int);

  void *vstr_parse_num(const struct Vstr_base *, size_t, size_t, unsigned int,
                       size_t  *, unsigned int *, void *(*)(unsigned int, int,
                       unsigned int *, void *), void *);
  short vstr_parse_short(const struct Vstr_base *,  size_t,  size_t,  unsigned
                         int, size_t *, unsigned int *);
  unsigned  short  vstr_parse_ushort(const struct Vstr_base *, size_t, size_t,
                                   unsigned int, size_t *, unsigned int *);
  int vstr_parse_int(const struct Vstr_base *, size_t, size_t,  unsigned  int,
                     size_t *, unsigned int *);
  unsigned  int  vstr_parse_uint(const  struct  Vstr_base  *,  size_t, size_t,
                               unsigned int, size_t *, unsigned int *);
  long vstr_parse_long(const struct Vstr_base *, size_t, size_t, unsigned int,
                       size_t *, unsigned int *);
  unsigned  long  vstr_parse_ulong(const  struct  Vstr_base *, size_t, size_t,
                                 unsigned int, size_t *, unsigned int *);
  intmax_t  vstr_parse_intmax(const  struct  Vstr_base  *,   size_t,   size_t,
                             unsigned int, size_t *, unsigned int *);
  uintmax_t  vstr_parse_uintmax(const  struct  Vstr_base  *,  size_t,  size_t,
                               unsigned int, size_t *, unsigned int *);
  size_t vstr_parse_netstr(const struct Vstr_base *, size_t, size_t, size_t *,
                           size_t *);
  size_t  vstr_parse_netstr2(const  struct Vstr_base *, size_t, size_t, size_t
                            *, size_t *);
  int vstr_parse_ipv4(const struct Vstr_base *, size_t, size_t, unsigned  char
                      *,  unsigned int *, unsigned int, size_t *, unsigned int
                      *);
  int vstr_parse_ipv6(const struct Vstr_base *, size_t, size_t,  unsigned  int
                      *,  unsigned int *, unsigned int, size_t *, unsigned int
                      *);

  int vstr_fmt_add(struct Vstr_conf *, const char *, int (*)(struct  Vstr_base



Vstr 1.0.15                06-Mar-2006                          8





vstr(3)                Vstr String Library                vstr(3)


                   *, size_t, struct Vstr_fmt_spec *), ...);
  void vstr_fmt_del(struct Vstr_conf *, const char *);
  int vstr_fmt_srch(struct Vstr_conf *, const char *);
  void *VSTR_FMT_CB_ARG_PTR(struct Vstr_fmt_spec *, size_t);
  Parameter[2] VSTR_FMT_CB_ARG_VAL(struct Vstr_fmt_spec *, <symbol>, size_t);

  void  vstr_sc_bmap_init_eq_spn_buf(const  unsigned  char[256], const void *,
                                    size_t, unsigned char);
  void vstr_sc_bmap_init_eq_spn_cstr(const unsigned char[256], const  char  *,
                                     unsigned char);
  void  vstr_sc_bmap_init_or_spn_buf(const  unsigned  char[256], const void *,
                                    size_t, unsigned char);
  void vstr_sc_bmap_init_or_spn_cstr(const unsigned char[256], const  char  *,
                                     unsigned char);
  size_t vstr_sc_posdiff(size_t, size_t);
  size_t VSTR_SC_POSDIFF(size_t, size_t);
  size_t vstr_sc_poslast(size_t, size_t);
  size_t VSTR_SC_POSLAST(size_t, size_t);
  int vstr_sc_reduce(struct Vstr_base *, size_t, size_t, size_t);
  void  vstr_sc_basename(const  struct  Vstr_base *, size_t, size_t, size_t *,
                        size_t *);
  int vstr_sc_add_grpbasenum_buf(const struct Vstr_base  *,  size_t,  unsigned
                                 int, const void *, size_t);
  int  vstr_sc_add_grpbasenum_ptr(const  struct  Vstr_base *, size_t, unsigned
                                 int, const void *, size_t);
  int vstr_sc_add_grpbasenum_ref(const struct Vstr_base  *,  size_t,  unsigned
                                 int, Vstr_ref *, size_t, size_t);
  int  vstr_sc_add_grpnum_buf(const  struct Vstr_base *, size_t, const void *,
                             size_t);
  int  vstr_sc_add_cstr_grpbasenum_buf(const  struct  Vstr_base   *,   size_t,
                                      unsigned int, const char *);
  int   vstr_sc_add_cstr_grpbasenum_ptr(const   struct  Vstr_base  *,  size_t,
                                      unsigned int, const char *);
  int  vstr_sc_add_cstr_grpbasenum_ref(const  struct  Vstr_base   *,   size_t,
                                      unsigned int, Vstr_ref *, size_t);
  int   VSTR_SC_ADD_CSTR_GRPBASENUM_BUF(const   struct  Vstr_base  *,  size_t,
                                      unsigned int, const char *);
  int  VSTR_SC_ADD_CSTR_GRPBASENUM_PTR(const  struct  Vstr_base   *,   size_t,
                                      unsigned int, const char *);
  int   VSTR_SC_ADD_CSTR_GRPBASENUM_REF(const   struct  Vstr_base  *,  size_t,
                                      unsigned int, Vstr_ref *, size_t);
  int vstr_sc_add_cstr_grpnum_buf(const struct Vstr_base *, size_t, const char
                                  *);
  int VSTR_SC_ADD_CSTR_GRPNUM_BUF(const struct Vstr_base *, size_t, const char
                                  *);
  size_t vstr_sc_conv_num_uint(char *, size_t, unsigned  int,  const  char  *,
                               unsigned int);
  size_t vstr_sc_conv_num10_uint(char *, size_t, unsigned int);
  size_t  vstr_sc_conv_num_ulong(char  *,  size_t, unsigned int, const char *,
                                unsigned long);
  size_t vstr_sc_conv_num10_ulong(char *, size_t, unsigned long);
  size_t vstr_sc_conv_num_size(char *, size_t, size_t, const char *,  unsigned
                               int);
  size_t vstr_sc_conv_num10_size(char *, size_t, size_t);



Vstr 1.0.15                06-Mar-2006                          9





vstr(3)                Vstr String Library                vstr(3)


  size_t  vstr_sc_conv_num_uintmax(char  *,  size_t,  uintmax_t, const char *,
                                  unsigned int);
  size_t vstr_sc_conv_num10_uintmax(char *, size_t, uintmax_t);
  void vstr_sc_dirname(const struct Vstr_base *, size_t, size_t, size_t *);
  int vstr_sc_fmt_cb_beg(struct Vstr_base *, size_t *, struct Vstr_fmt_spec *,
                         size_t *, unsigned int);
  int  vstr_sc_fmt_cb_end(struct  Vstr_base *, size_t, struct Vstr_fmt_spec *,
                         size_t);
  int vstr_sc_fmt_add_vstr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_buf(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ptr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_non(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ref(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_rep_chr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_Byte_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_Bytes_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_bit_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_bits_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_Byte_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_Bytes_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_bit_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_bkmg_bits_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv4_ptr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv6_ptr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv4_vec(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv6_vec(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv4_vec_cidr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_ipv6_vec_cidr(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_upper_base2_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_upper_base2_ulong(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_upper_base2_size(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_upper_base2_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_lower_base2_uint(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_lower_base2_ulong(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_lower_base2_size(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_lower_base2_uintmax(struct Vstr_conf *, const char *);
  int vstr_sc_fmt_add_all(struct Vstr_conf *);
  int VSTR_SC_FMT_ADD(struct Vstr_conf *, int (*)(struct  Vstr_conf  *,  const
                      char *), const char *, const char *, const char *);
  int  vstr_sc_mmap_fd(struct  Vstr_base  *,  size_t,  int,  off64_t,  size_t,
                      unsigned int *);
  int vstr_sc_mmap_file(struct Vstr_base *, size_t,  const  char  *,  off64_t,
                        size_t, unsigned int *);
  int  vstr_sc_read_iov_fd(struct  Vstr_base  *,  size_t,  int,  unsigned int,
                          unsigned int, unsigned int *);
  int vstr_sc_read_len_fd(struct Vstr_base *, size_t,  int,  size_t,  unsigned
                          int *);
  int vstr_sc_read_iov_file(struct Vstr_base *, size_t, const char *, off64_t,
                            unsigned int, unsigned int, unsigned int *);
  int vstr_sc_read_len_file(struct Vstr_base *, size_t, const char *, off64_t,
                            size_t, unsigned int *);
  int  vstr_sc_write_fd(struct  Vstr_base *, size_t, size_t, int, unsigned int
                       *);
  int vstr_sc_write_file(struct Vstr_base *, size_t,  size_t,  const  char  *,



Vstr 1.0.15                06-Mar-2006                         10





vstr(3)                Vstr String Library                vstr(3)


                         int, mode_t, off64_t, unsigned int *);
  int vstr_sc_add_b_uint16(struct Vstr_base *, size_t, uint_least16_t);
  int vstr_sc_add_b_uint32(struct Vstr_base *, size_t, uint_least32_t);
  int     vstr_sc_sub_b_uint16(struct    Vstr_base    *,    size_t,    size_t,
                           uint_least16_t);
  int    vstr_sc_sub_b_uint32(struct    Vstr_base    *,    size_t,     size_t,
                           uint_least32_t);
  uint_least16_t vstr_sc_parse_b_uint16(struct Vstr_base *, size_t);
  uint_least32_t vstr_sc_parse_b_uint32(struct Vstr_base *, size_t);

  int  vstr_iter_fwd_beg(struct  Vstr_base *, size_t, size_t, struct Vstr_iter
                        *);
  int vstr_iter_fwd_nxt(struct Vstr_iter *);
  char vstr_iter_fwd_chr(struct Vstr_iter *, unsigned int *);
  size_t  vstr_iter_fwd_buf(struct  Vstr_iter  *,  size_t,  void  *,   size_t,
                           unsigned int *);
  size_t  vstr_iter_fwd_cstr(struct  Vstr_iter  *,  size_t,  char  *,  size_t,
                            unsigned int *);
  size_t vstr_iter_pos(struct Vstr_iter *, size_t, size_t);
  size_t vstr_iter_len(struct Vstr_iter *);

  int vstr_cntl_opt(int, ...);
  int vstr_cntl_base(const struct Vstr_base *, int, ...);
  int vstr_cntl_conf(struct Vstr_conf *, int, ...);
  unsigned int VSTR_FLAGXX(<symbol>, <symbol>);
  unsigned int vstr_num(const struct Vstr_base *, size_t, size_t);
  unsigned  int  vstr_cache_add(struct  Vstr_conf  *,  const  char   *,   void
                              *(*)(const  struct  Vstr_base *, size_t, size_t,
                              unsigned int, void *));
  void *vstr_cache_get(const struct Vstr_base *, unsigned int);
  int vstr_cache_set(const struct Vstr_base *, unsigned int, void *);
  unsigned int vstr_cache_srch(struct Vstr_conf *, const char *);
  void vstr_cache_cb_sub(const struct Vstr_base *, size_t, size_t);
  void vstr_cache_cb_free(const struct Vstr_base *, unsigned int);
  unsigned int vstr_data_add(struct Vstr_conf *, const char *, struct Vstr_ref
                             *);
  unsigned int vstr_data_srch(struct Vstr_conf *, const char *);
  void vstr_data_del(struct Vstr_conf *, unsigned int);
  void *vstr_data_get(struct Vstr_conf *, unsigned int);
  void vstr_data_set(struct Vstr_conf *, unsigned int, struct Vstr_ref *);
  int vstr_swap_conf(struct Vstr_base *, struct Vstr_conf **);


DESCRIPTION
        A  very  simple  overview is that you call vstr_init() at the start of
       your program and vstr_exit() at the end.
        You can make new Vstr strings by calling  vstr_make_base(),  and  free
       them  by  calling  vstr_free_base(). There are also a vstr_dup_* set of
       functions to make a new Vstr string with data in them.
        You can then add/delete data from  this  string,  using  the  provided
       functions,  if  you  need  to  use  all or part of the string with a "C
       string"  interface  then  you  can   call   vstr_export_cstr_ptr()   or
       vstr_export_cstr_malloc().




Vstr 1.0.15                06-Mar-2006                         11





vstr(3)                Vstr String Library                vstr(3)


Library initialization and exit functions
     Function:  vstr_init()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Nothing
       Type[1]: void

       Explanation:

         This  function  needs  to be called before any of the other functions
       are called.

       Note:

         The function can be called multiple times, without any problems.

     Function:  vstr_exit()
       Returns: Nothing
       Type: void

       Parameter[1]: Nothing
       Type[1]: void

       Explanation:

         This function can be called before exit, after all vstr objects  have
       been freed, to cleanup data allocated internally in the Vstr library.

       Note:

         The  function  isn't  needed  but helps make sure there are no memory
       leaks, when used with a memory checker (or  with  the  internal  memory
       checker in the debug build).


Exporting data functions
     Function:  vstr_export_cstr_ptr()
       Returns: A pointer to an array of characters, terminated by NIL
       Type: const char *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Explanation:

         This  function  is used to export a pointer to an array of characters
       of length (Parameter[3] + 1), the last byte will be a  0  to  terminate



Vstr 1.0.15                06-Mar-2006                         12





vstr(3)                Vstr String Library                vstr(3)


       the "C string".
         Multiple adjacent calls will return the same pointer.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return NULL if it needs to allocate memory and can-
       not do so.

       Note:

         If  you  alter the Vstr in anyway then the returned pointer may point
       to  free()'d  memory.  To  get   a   reference   to   this   data   use
       vstr_export_cstr_ref() instead.
         This data needs to be cached in the Vstr string, and so can only work
       if  the  Vstr   string   has   the   ability   to   cache   data   (see
       VSTR_CNTL_BASE_GET_FLAG_HAVE_CACHE).  If you want to make sure that the
       cached data is gone from the Vstr  string,  cache  then  you  can  call
       vstr_cache_cb_free() on the cookie from "/vstr__/cstr".
         Any  _NON  data  in  the  Vstr  will  be uninitialized data in the "C
       string".
         If there are any 0 bytes in the Vstr they will make the  string  look
       shorter than it really is to normal C style string functions.

     Function:  vstr_export_cstr_malloc()
       Returns:  A  malloc'd  pointer to an array of characters, terminated by
       NIL
       Type: char *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Explanation:

         This function is used to export a malloc'd pointer  to  an  array  of
       characters  of  length (Parameter[3] + 1), the last byte will be a 0 to
       terminate the "C string". You will need to pass the pointer to  free(),
       when you are done with it.
         Each call will return a different pointer.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return NULL if it needs to allocate memory and can-
       not do so.

       Note:

         Any  _NON  data  in  the  Vstr  will  be uninitialized data in the "C
       string".
         If there are any 0 bytes in the Vstr they will make the  string  look
       shorter than it really is to normal C/POSIX string functions.



Vstr 1.0.15                06-Mar-2006                         13





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_export_cstr_buf()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Parameter[4]: Data array to export to
       Type[4]: void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to export a copy of the data in the Vstr string
       to a data array, the maximum amount of data stored in the array will be
       of  length  (Parameter[3]  + 1), the last byte will be a 0 to terminate
       the "C string". However the  data  before  the  terminator  of  the  "C
       string" is limited to (Parameter[5] - 1).

       Note:

         Data from nodes of type NON are exported by not doing anything to the
       underlying data array (Ie. It'll have whatever data  was  in  there  to
       start with).
         If  there  are  any 0 bytes in the Vstr they will make the "C string"
       look shorter than it really is to normal C/POSIX string functions.

     Function:  vstr_export_cstr_ref()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Parameter[4]: Offset of Vstr memory reference (Return)
       Type[4]: size_t *

       Explanation:

         This function is used to return a pointer to a Vstr memory  reference



Vstr 1.0.15                06-Mar-2006                         14





vstr(3)                Vstr String Library                vstr(3)


       of  at  least  length  (Parameter[3] + 1), the last byte will be a 0 to
       terminate the "C  string"  stored  in  (Vstr_ref  *)->ptr.  The  offset
       (Parameter[4])  should  be  used  to find the beginning of the block of
       memory to use.
         When  you  are  finished  with  the  reference  you   need   to   use
       vstr_ref_del() or the memory will stay allocated forever.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return NULL if it needs to allocate memory and can-
       not do so.

       Note:

         If  you  want to make sure that the cached data is gone from the Vstr
       string, cache then you can call vstr_cache_cb_free() on the cookie from
       "/vstr__/cstr".
         Any  _NON  data  in  the  Vstr  will  be uninitialized data in the "C
       string".
         If there are any 0 bytes in the Vstr they will make the  string  look
       shorter than it really is to normal C/POSIX string functions.

     Function:  vstr_export_iovec_ptr_all()
       Returns: Size of bytes in the Vstr string
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Returns the start of the iovec array
       Type[2]: struct iovec **

       Parameter[2]: Returns the number of iovec structures in the array
       Type[2]: unsigned int *

       Explanation:

         This function is used to export a pointer to an array of iovec struc-
       tures this can then be passed directly to writev() etc. or just used to
       quickly access the data in the Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so.

       Note:

         Nodes of type NON are represented by a iov_base set to NULL.
         Altering  the  iov_base/iov_len  members  will  probably  do very bad
       things, if you need to do this use the vstr_export_iovec_cpy_ptr()
         Altering the data in the iovec structure isn't  a  good  idea  as  it
       isn't  easy  for the programer to know if the data is shared/read-only.
       If you need to do this you should use either the  vstr_sub_*  functions
       instead or vstr_export_iovec_cpy_buf() (the later does a copy). However
       if you do alter the data then you'll need to do vstr_cache_cb_sub().



Vstr 1.0.15                06-Mar-2006                         15





vstr(3)                Vstr String Library                vstr(3)


         Either of the pointers for the iovec array (Parameter[2]) or the num-
       ber  of  iovecs  (Parameter[3])  can be the NULL pointer, in which case
       nothing will be written to those pointers.

     Function:  vstr_export_iovec_cpy_buf()
       Returns: Size of bytes exported from the Vstr string
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to array of initialized iovec structures
       Type[4]: struct iovec *

       Parameter[5]: Number of iovec structures (Parameter[4])
       Type[5]: unsigned int

       Parameter[6]: Returns the number of iovec structures used in the array
       Type[6]: unsigned int *

       Explanation:

         This function is used to export a copy of the data in the Vstr string
       to  an  array  of  iovec structures this can then be passed directly to
       writev() (or even a readv() although that  wouldn't  often  be  useful)
       etc.
         Think of this function as doing a readv() from a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         Data from nodes of type NON are exported by not doing anything to the
       underlying  iov_base  data  arrays (Ie. It'll have whatever data was in
       there to start with).
         The length returned may be shorter than that given  as  Parameter[3],
       as  it's  the  number  of  bytes copied into the iov_base arrays in the
       iovec structures.

     Function:  vstr_export_iovec_cpy_ptr()
       Returns: Size of bytes exported from the Vstr string
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t



Vstr 1.0.15                06-Mar-2006                         16





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to array of iovec structures
       Type[4]: struct iovec *

       Parameter[5]: Number of iovec structures (Parameter[4])
       Type[5]: unsigned int

       Parameter[6]: Returns the number of iovec structures used in the array
       Type[6]: unsigned int *

       Explanation:

         This function is used to export a set of pointer/length pairs to  the
       data  specified in the Vstr string, this can then be passed directly to
       writev() etc.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         Nodes of type NON are represented by a iov_base set to NULL.
         Altering  the  data  in  the  iovec structure isn't a good idea as it
       isn't easy for the programer to know if the data  is  shared/read-only.
       If  you  need to do this you should use either the vstr_sub_* functions
       instead or vstr_export_iovec_cpy_buf() (the later does a copy).

     Function:  vstr_export_buf()
       Returns: Size of bytes exported from the Vstr string
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Data array to export to
       Type[4]: void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to export a copy of the data in the Vstr string
       to a data array.
         Think  of this function as doing a read() from a Vstr string. However
       the data will be limited to the minimum  of  the  length  of  the  vstr
       (Parameter[3]) and the length of the data (Parameter[5]).



Vstr 1.0.15                06-Mar-2006                         17





vstr(3)                Vstr String Library                vstr(3)


         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         Data from nodes of type NON are exported by not doing anything to the
       underlying  data  array  (Ie.  It'll have whatever data was in there to
       start with).

     Function:  vstr_export_chr()
       Returns: Character exported from the Vstr string
       Type: char

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Explanation:

         This function is used to return a character at a certain position  in
       a Vstr string.

       Note:

         It  is  impossible  to  distinguish between an error, data from a NON
       node and real data that is equal to the value 0.

     Function:  vstr_export_ref()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Parameter[4]: Offset of Vstr memory reference (Return)
       Type[4]: size_t *

       Explanation:

         This function is used to return a pointer to a Vstr memory  reference
       of  at least length (Parameter[3]). The offset (Parameter[4]) should be
       used to find the beginning of the block of memory to use.
         When  you  are  finished  with  the  reference  you   need   to   use
       vstr_ref_del() or the memory will stay allocated forever.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.



Vstr 1.0.15                06-Mar-2006                         18





vstr(3)                Vstr String Library                vstr(3)


         The function will return NULL if it needs to allocate memory and can-
       not do so.

       Note:

         Any  _NON  data  in the Vstr will be uninitialized data in the memory
       pointed to by the memory reference.


Memory reference functions
     Function:  vstr_ref_add()
       Returns: Vstr memory reference (Parameter[1])
       Type: struct Vstr_ref *

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:

         This function will add a reference count  to  the  Vstr_ref  (Parame-
       ter[1]).

     Function:  vstr_ref_del()
        Returns:.br Type: void

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:

         This function will delete a reference count from the Vstr_ref (Param-
       eter[1]), when the reference count reaches zero then the cleanup  func-
       tion will be called.

     Function:  vstr_ref_cb_free_nothing()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:

         This function does nothing.

     Function:  vstr_ref_cb_free_ref()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:




Vstr 1.0.15                06-Mar-2006                         19





vstr(3)                Vstr String Library                vstr(3)


         This will call free() on the Vstr_ref (Parameter[1]).

     Function:  vstr_ref_cb_free_ptr()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:

         This will call free() on the data in the Vstr_ref (Parameter[1])->ptr
       (unless the passed reference is the NULL pointer, then  it  does  noth-
       ing).

     Function:  vstr_ref_cb_free_ptr_ref()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr memory reference
       Type[1]: struct Vstr_ref *

       Explanation:

         This will call free() on the data in the Vstr_ref (Parameter[1])->ptr
       and then call free() on the Vstr_ref (Parameter[1]) (unless the  passed
       reference is the NULL pointer, then it does nothing).

     Function:  vstr_ref_make_malloc()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Size of malloc'd area to create in the memory reference
       Type[1]: size_t

       Explanation:

         This function will create an area of memory, using malloc, and create
       a Vstr memory reference to that memory. The Vstr memory reference  will
       have  a  reference  count of 1 and the cleanup function will point to a
       function to free both the reference and the copy of memory.

     Function:  vstr_ref_make_ptr()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Pointer to memory
       Type[1]: void *

       Parameter[2]: Function callback for Vstr memory reference
       Type[2]: void (*)(struct Vstr_ref *)

       Explanation:




Vstr 1.0.15                06-Mar-2006                         20





vstr(3)                Vstr String Library                vstr(3)


         This function will call malloc() to create a Vstr  memory  reference.
       The  Vstr  memory reference will have a reference count of 1, a pointer
       value of pointer passed (Parameter[1]) and a cleanup  function  of  the
       function passed (Parameter[2]).

     Function:  vstr_ref_make_memdup()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Pointer to memory
       Type[1]: void *

       Parameter[2]: Length of memory block
       Type[2]: size_t

       Explanation:

         This  function  will  create a Vstr memory reference. The Vstr memory
       reference will have a reference count of 1 and a  copy  of  the  memory
       pointed  to  by  (Parameter[1])  of  length  (Parameter[2]) will be the
       pointer value. The cleanup function will point to a  function  to  free
       both the reference and the copy of memory.

     Function:  vstr_ref_make_strdup()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Pointer to data
       Type[1]: char *

       Explanation:

         This  function calls vstr_ref_make_memdup() with the length being the
       value of (strlen() + 1) on the data parameter (Parameter[1]).

     Function:  VSTR_REF_MAKE_STRDUP()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Pointer to data
       Type[1]: char *

       Explanation:

         This macro function  calls  vstr_ref_make_memdup()  with  the  length
       being the value of (strlen() + 1) on the data parameter (Parameter[1]).

     Function:  vstr_ref_make_vstr_base()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         21





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function will create a Vstr memory reference.  The  Vstr  memory
       reference will have a reference count of 1, a pointer value of the Vstr
       string (Parameter[1]). The cleanup function will point to a function to
       free both the reference and the Vstr string.

     Function:  vstr_ref_make_vstr_conf()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Explanation:

         This  function  will  create a Vstr memory reference. The Vstr memory
       reference will have a reference count of 1, a pointer value of the Vstr
       configuration  (Parameter[1]).  The  cleanup  function  will point to a
       function to free both the reference and the Vstr configuration.

     Function:  vstr_ref_make_vstr_sects()
       Returns: Vstr memory reference
       Type: struct Vstr_ref *

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Explanation:

         This function will create a Vstr memory reference.  The  Vstr  memory
       reference will have a reference count of 1, a pointer value of the Vstr
       sections (Parameter[1]). The cleanup function will point to a  function
       to free both the reference and the Vstr sections.


Creation/destruction of core objects
     Function:  vstr_make_conf()
       Returns: Vstr configuration
       Type: struct Vstr_conf *

       Parameter[1]: Nothing
       Type[1]: void

       Explanation:

         This function will make a Vstr configuration, or return NULL.

     Function:  vstr_free_conf()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *



Vstr 1.0.15                06-Mar-2006                         22





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This   function   will   free  a  Vstr  configuration,  allocated  by
       vstr_make_conf().

     Function:  vstr_make_base()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Explanation:

         This function will make a Vstr string, or return NULL.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         If there are spare base objects, then no allocations are done.

     Function:  vstr_free_base()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Explanation:

         This function will free a Vstr string, allocated by vstr_make_base().

       Note:

         If the base object VSTR_CNTL_BASE_GET_TYPE_GRPALLOC_CACHE is  of  the
       same   type   as   it's  configurations  VSTR_CNTL_CONF_GET_TYPE_GRPAL-
       LOC_CACHE, then the base object will be turned into a spare  object  so
       it can be reused by vstr_make_base().

     Function:  vstr_dup_buf()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const void *

       Parameter[3]: Length of data (Parameter[2])
       Type[3]: size_t

       Explanation:



Vstr 1.0.15                06-Mar-2006                         23





vstr(3)                Vstr String Library                vstr(3)


         This  function  is  equivalent  to  calling vstr_make_base() and then
       vstr_add_buf().

     Function:  vstr_dup_ptr()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const void *

       Parameter[3]: Length of data (Parameter[2])
       Type[3]: size_t

       Explanation:

         This function is equivalent  to  calling  vstr_make_base()  and  then
       vstr_add_ptr().

     Function:  vstr_dup_non()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Length of non data
       Type[2]: size_t

       Explanation:

         This  function  is  equivalent  to  calling vstr_make_base() and then
       vstr_add_non().

     Function:  vstr_dup_ref()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Vstr memory reference
       Type[2]: struct Vstr_ref *

       Parameter[3]: Offset of Vstr memory reference (Parameter[2])
       Type[3]: size_t

       Parameter[4]: Length of Vstr memory reference (Parameter[2])
       Type[4]: size_t

       Explanation:




Vstr 1.0.15                06-Mar-2006                         24





vstr(3)                Vstr String Library                vstr(3)


         This function is equivalent  to  calling  vstr_make_base()  and  then
       vstr_add_ref().

     Function:  vstr_dup_vstr()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Vstr string
       Type[2]: const struct Vstr_base *

       Parameter[3]: Start position in the Vstr string (Parameter[2])
       Type[3]: size_t

       Parameter[4]: Length in the Vstr string (Parameter[2])
       Type[4]: size_t

       Parameter[6]: Flags for Vstr add (VSTR_TYPE_ADD_*)
       Type[6]: unsigned int

       Explanation:

         This  function  is  equivalent  to  calling vstr_make_base() and then
       vstr_add_vstr().

     Function:  vstr_dup_rep_chr()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Character to repeat
       Type[2]: char

       Parameter[3]: Number of times to repeat character (Parameter[2])
       Type[3]: size_t

       Explanation:

         This function is equivalent  to  calling  vstr_make_base()  and  then
       vstr_add_rep_chr().

     Function:  vstr_dup_cstr_buf()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const char *



Vstr 1.0.15                06-Mar-2006                         25





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function calls vstr_dup_buf() with the length being the value of
       strlen() on the data parameter (Parameter[2]).

     Function:  vstr_dup_cstr_ptr()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const char *

       Explanation:

         This function calls vstr_dup_ptr() with the length being the value of
       strlen() on the data parameter (Parameter[2]).

     Function:  vstr_dup_cstr_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Vstr memory reference
       Type[2]: struct Vstr_ref *

       Parameter[3]: Offset of Vstr memory reference (Parameter[3])
       Type[3]: size_t


       Explanation:

         This function calls vstr_dup_ref() with the length being the value of
       strlen() on the memory from the Vstr  memory  reference  (Parameter[3])
       starting at the offset (Parameter[4]).

     Function:  VSTR_DUP_CSTR_BUF()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const char *

       Explanation:

         This  macro  function  calls vstr_dup_buf() with the length being the
       value of strlen() on the data parameter (Parameter[2]).



Vstr 1.0.15                06-Mar-2006                         26





vstr(3)                Vstr String Library                vstr(3)


     Function:  VSTR_DUP_CSTR_PTR()
       Returns: Vstr string
       Type: struct Vstr_base *

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Pointer to data
       Type[2]: const char *

       Explanation:

         This macro function calls vstr_dup_ptr() with the  length  being  the
       value of strlen() on the data parameter (Parameter[2]).

     Function:  VSTR_DUP_CSTR_REF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Vstr memory reference
       Type[2]: struct Vstr_ref *

       Parameter[3]: Offset of Vstr memory reference (Parameter[3])
       Type[3]: size_t


       Explanation:

         This  macro  function  calls vstr_dup_ref() with the length being the
       value of strlen() on the memory from the Vstr memory reference (Parame-
       ter[3]) starting at the offset (Parameter[4]).

     Function:  vstr_make_spare_nodes()
       Returns: Number of nodes created
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Type of nodes to create
       Type[2]: unsigned int

       Parameter[3]: Number of nodes to create
       Type[3]: unsigned int

       Explanation:

         This function will try and create a number (Parameter[3]) of nodes of
       type (Parameter[2]).

       Note:



Vstr 1.0.15                06-Mar-2006                         27





vstr(3)                Vstr String Library                vstr(3)


         The number of nodes created will be less than or equal to the  number
       requested  (Parameter[3]),  however  if  it  is less than then the mal-
       loc_bad flag will be set (Parameter[1])->malloc_bad.
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_free_spare_nodes()
       Returns: Number of nodes destroyed
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Type of nodes to destroy
       Type[2]: unsigned int

       Parameter[3]: Number of nodes to destroy
       Type[3]: unsigned int

       Explanation:

         This  function  will try and destroy a number (Parameter[3]) of nodes
       of type (Parameter[2]).

       Note:

         The number of nodes destroyed will be less than or equal to the  num-
       ber  requested  (Parameter[3]),  the  only  reason  that  less  will be
       destroyed is if there are no more unused nodes of  that  type  (Parame-
       ter[2]).
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.


Adding and deleting of data functions
     Function:  vstr_add_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const void *

       Parameter[4]: Length of data (Parameter[3])
       Type[4]: size_t

       Explanation:

         This function is used to add a copy of the data in the data array  to



Vstr 1.0.15                06-Mar-2006                         28





vstr(3)                Vstr String Library                vstr(3)


       a Vstr string.
         Think of this function as doing a write() into a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

     Function:  vstr_add_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const void *

       Parameter[4]: Length of data (Parameter[3])
       Type[4]: size_t

       Explanation:

         This function is used to add a pointer to a  data  array  to  a  Vstr
       string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         If the data in the array needs to be free'd the programer  will  have
       to  decide  when it is no longer being used by the Vstr string and free
       it.  It  is  often  easier  to  create  a  memory  reference  and   use
       vstr_add_ref() instead.

     Function:  vstr_add_non()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length of non data
       Type[3]: size_t




Vstr 1.0.15                06-Mar-2006                         29





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This  function  is  used  to  add "non" (or invisible) data to a Vstr
       string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

     Function:  vstr_add_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Vstr memory reference
       Type[3]: struct Vstr_ref *

       Parameter[4]: Offset of Vstr memory reference (Parameter[3])
       Type[4]: size_t

       Parameter[5]: Length of Vstr memory reference (Parameter[3])
       Type[5]: size_t

       Explanation:

         This function is used to add a memory reference to a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

     Function:  vstr_add_vstr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Vstr string
       Type[3]: const struct Vstr_base *

       Parameter[4]: Start position in the Vstr string (Parameter[3])
       Type[4]: size_t




Vstr 1.0.15                06-Mar-2006                         30





vstr(3)                Vstr String Library                vstr(3)


       Parameter[5]: Length in the Vstr string (Parameter[3])
       Type[5]: size_t

       Parameter[6]: Type for Vstr add (VSTR_TYPE_ADD_*)
       Type[6]: unsigned int

       Explanation:

         This function is used to add data in one Vstr  string  (Parameter[3])
       to another Vstr string (Parameter[1]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         The function can change how the data is  added  to  the  Vstr  string
       (Parameter[1])  and  in  some cases even how the data is represented in
       the Vstr string (Parameter[3]) for more information see the  documenta-
       tion on the VSTR_TYPE_ADD_* constants.
         This  function  will  set _both_ (Parameter[1])->conf->malloc_bad and
       (Parameter[3])->conf->malloc_bad if any of the allocation calls  fails.

     Function:  vstr_add_rep_chr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Character to repeat
       Type[3]: char

       Parameter[4]: Number of times to repeat character (Parameter[3])
       Type[4]: size_t

       Explanation:

         This  function  is  used  to  add  1  or more copies of the character
       (Parameter[3]) to the Vstr string.
         Think of this function as doing a memset()  into  data  in  the  Vstr
       string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

     Function:  vstr_add_cstr_buf()



Vstr 1.0.15                06-Mar-2006                         31





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const char *

       Explanation:

         This function calls vstr_add_buf() with the length being the value of
       strlen() on the data parameter (Parameter[3]).

     Function:  vstr_add_cstr_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const char *

       Explanation:

         This function calls vstr_add_ptr() with the length being the value of
       strlen() on the data parameter (Parameter[3]).

     Function:  vstr_add_cstr_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Vstr memory reference
       Type[3]: struct Vstr_ref *

       Parameter[4]: Offset of Vstr memory reference (Parameter[3])
       Type[4]: size_t


       Explanation:




Vstr 1.0.15                06-Mar-2006                         32





vstr(3)                Vstr String Library                vstr(3)


         This function calls vstr_add_ref() with the length being the value of
       strlen()  on  the  memory from the Vstr memory reference (Parameter[3])
       starting at the offset (Parameter[4]).

     Function:  VSTR_ADD_CSTR_BUF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const char *

       Explanation:

         This macro function calls vstr_add_buf() with the  length  being  the
       value of strlen() on the data parameter (Parameter[3]).

     Function:  VSTR_ADD_CSTR_PTR()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const char *

       Explanation:

         This  macro  function  calls vstr_add_ptr() with the length being the
       value of strlen() on the data parameter (Parameter[3]).

     Function:  VSTR_ADD_CSTR_REF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Vstr memory reference
       Type[3]: struct Vstr_ref *

       Parameter[4]: Offset of Vstr memory reference (Parameter[3])



Vstr 1.0.15                06-Mar-2006                         33





vstr(3)                Vstr String Library                vstr(3)


       Type[4]: size_t


       Explanation:

         This macro function calls vstr_add_ref() with the  length  being  the
       value of strlen() on the memory from the Vstr memory reference (Parame-
       ter[3]) starting at the offset (Parameter[4]).

     Function:  vstr_add_vfmt()
       Returns: Number of bytes added
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Format string, a superset of the rules for C99 printf
       Type[3]: const char *

       Parameter[4]: Standard argument object from va_start()
       Type[4]: va_list

       Explanation:

         This function works like calling  vsprintf()  directly  into  a  Vstr
       string, however this is a portable implementation which is feature com-
       plete with glibc-2.2.x sprintf(); implements custom specifiers, if  you
       use the vstr_fmt_add() function, and doesn't require a double copy.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         Depending on how the library was compiled double  support  is  imple-
       mented   by  either  calling  the  underlying  host  implementation  of
       sprintf(), by internal code or simply  by  assuming  all  double's  are
       zero. When using the host implementation system bugs of inaccuracy will
       show through, however the feature set remains the same (Ie. the '  flag
       works the same).
         Because  specifiers can be overridden using vstr_fmt_add() if you are
       adding data to a Vstr string that you  didn't  create  you  should  use
       either vstr_add_vsysfmt() or vstr_swap_conf().

     Function:  vstr_add_fmt()
       Returns: Number of bytes added
       Type: size_t

       Parameter[1]: Vstr string



Vstr 1.0.15                06-Mar-2006                         34





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Format string, a superset of the rules for C99 printf
       Type[3]: const char *

       Parameter[4]: Options depending on value of Parameter[3]
       Type[4]: ...

       Explanation:

         This  just  calls  vstr_add_vfmt() after converting the argument list
       (Parameter[4]) a va_list object.

     Function:  vstr_add_vsysfmt()
       Returns: Number of bytes added
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Format string, a superset of the rules for C99 printf
       Type[3]: const char *

       Parameter[4]: Standard argument object from va_start()
       Type[4]: va_list

       Explanation:

         This function does the same thing as vstr_add_vfmt() but ignores cus-
       tom specifiers (see vstr_fmt_add()).

     Function:  vstr_add_sysfmt()
       Returns: Number of bytes added
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Format string, a superset of the rules for C99 printf
       Type[3]: const char *

       Parameter[4]: Options depending on value of Parameter[3]
       Type[4]: ...

       Explanation:



Vstr 1.0.15                06-Mar-2006                         35





vstr(3)                Vstr String Library                vstr(3)


         This just calls vstr_add_vsysfmt() after converting the argument list
       (Parameter[4]) a va_list object.

     Function:  vstr_add_iovec_buf_beg()
       Returns: Number of bytes in the iovec array
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Minimum amount of iovecs to add
       Type[3]: unsigned int

       Parameter[4]: Maximum amount of iovecs to add
       Type[4]: unsigned int

       Parameter[5]: Returns the start of the iovec array
       Type[5]: struct iovec **

       Parameter[6]: Returns the number of iovec structures in the array
       Type[6]: unsigned int *

       Explanation:

         This function is used to add a copy of data directly  into  the  Vstr
       string,  the  amount  of  data  available  will  be between the minimum
       (Parameter[4]) and maximum ((Parameter[5]) + 1) number of iovecs multi-
       plied by the length of data in _BUF type nodes. The obvious use for the
       data is to call readv() on it.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         You    shouldn't    call    any    other   vstr   functions   between
       vstr_add_iovec_buf_beg() and vstr_add_iovec_buf_end(), unless you  know
       that  they  are  operating  on a different Vstr string which is using a
       different Vstr configuration.
         The reason there is a +1 on the maximum value is  that  data  may  be
       appended  to  a _BUF node just before the start of where the data is to
       go, this is almost guaranteed to happen when adding to  the  end  of  a
       Vstr string and saves a lot of wasted space.
         It  is  currently  believed  that, on Linux, doing disk IO in amounts
       greater than 8k gives little real performance improvement. This can  be
       converted into iovec numbers by using a formula like...

           min = (8k / buf_sz) + 2;
           max = min + (min / 2);



Vstr 1.0.15                06-Mar-2006                         36





vstr(3)                Vstr String Library                vstr(3)


        ...where  the +2 is due to both the extra space at the end of the cur-
       rent last
        node, and rounding errors due to the division. The max being  slightly
       bigger is an attempt to make the constant overhead of the call slightly
       less, and may not be useful. It is very  possible  that  some  kind  of
       dynamic  scaling  of  the  values would result in the best performance,
       however the solution to that doesn't fit in the margin :).

     Function:  vstr_add_iovec_buf_end()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number of bytes added to the iovec array
       Type[3]: size_t

       Explanation:

         This function is  used  after  calling  vstr_add_iovec_buf_beg()  and
       you've then filled in a bunch of data.

       Note:

         Although  it's safe to not bother calling this function if you didn't
       have anything to add to the Vstr string it is often more  efficient  to
       call this function with Parameter[3] as 0.
     Function:  vstr_add_netstr_beg()
       Returns: Position of start of netstr (Parameter[2]) + 1
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Explanation:

         This     function     creates    the    start    of    a    netstring
       http://cr.yp.to/proto/netstrings.txt this can be  used  in  conjunction
       with vstr_add_netstr_end() to easily create netstrings.

     Function:  vstr_add_netstr_end()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         37





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Position returned from vstr_add_netstr_beg()
       Type[2]: size_t

       Parameter[3]: End of netstring
       Type[3]: size_t

       Explanation:

         This  function  is called after calling vstr_add_netstr_beg(), adding
       all the data you want to the netstring and then passing the position of
       the end of that data.
         Upon  success  a  valid  netstring  will  contain  all the data added
       between the two calls.

       Note:

         It is valid to pass the same values for (Parameter[2])  and  (parame-
       ter[3]), as that signifies that there is no data in the netstring.
         It  is  almost  guaranteed that data will need to be removed from the
       beginning of the netstring due to the length  being  shorter  than  the
       maximum,  this  is inefficient and could cause problems if you know how
       big the Vstr string is you can use the vstr_add_netstr2_* functions  to
       solve both problems.

     Function:  vstr_add_netstr2_beg()
       Returns: Position of start of netstr (Parameter[2]) + 1
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Explanation:

         This  function creates the start of a netstring2 which is like a net-
       string http://cr.yp.to/proto/netstrings.txt but can have leading zeros,
       this  can  be used in conjunction with vstr_add_netstr2_end() to easily
       create netstring2s.

     Function:  vstr_add_netstr2_end()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Position returned from vstr_add_netstr2_beg()
       Type[2]: size_t

       Parameter[3]: End of netstring2
       Type[3]: size_t




Vstr 1.0.15                06-Mar-2006                         38





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is called after calling vstr_add_netstr2_beg(),  adding
       all  the  data you want to the netstring2 and then passing the position
       of the end of that data.
         Upon success a netstring2 will contain all the data added between the
       two calls.

       Note:

         It  is  valid to pass the same values for (Parameter[2]) and (parame-
       ter[3]), as that signifies that there is no data in the netstring.
         No data is ever removed from the beginning of a netstring2,  this  is
       incompatible with the netstring spec. but is more efficient and doesn't
       cause problems if you know how big the Vstr string is and can't have it
       lose data from the beginning/middle.

     Function:  vstr_del()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         This function is used to delete data in the Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         Deleted nodes do not get returned to the system, they get put into  a
       pool  in  the  Vstr  configuration  for  reuse  on  the  next call to a
       vstr_add_*() function.
         Deleting the entire Vstr  string  and  deleting  from  the  beginning
       onward  are  faster  operations  than a generic delete. They also never
       require allocating memory and so the return value can be ignored.

     Function:  vstr_mov()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *



Vstr 1.0.15                06-Mar-2006                         39





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Vstr string
       Type[3]: struct Vstr_base *

       Parameter[4]: Start position in the Vstr string (Parameter[3])
       Type[4]: size_t

       Parameter[5]: Length in the Vstr string (Parameter[3])
       Type[5]: size_t

       Explanation:

         This function is used to move data, deleting it from one Vstr  string
       (Parameter[3]) and adding it to another Vstr string (Parameter[1]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).


Substitution of data functions
     Function:  vstr_sub_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to substitute the data in the Vstr string  with
       a copy of the data in the data array.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The function will return 0 if it needs to allocate memory and  cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:



Vstr 1.0.15                06-Mar-2006                         40





vstr(3)                Vstr String Library                vstr(3)


         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[5]).
         Think   of   this   function   as  doing  a  vstr_del()  and  then  a
       vstr_add_buf() (but it's atomic).
         If the length of the data (Parameter[5]) is less than or equal to the
       length  of  the  Vstr  string  (Parameter[3])  and the data in the Vstr
       string is in a BUF node then the data will just be overwritten (Ie.  no
       allocations will happen).

     Function:  vstr_sub_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  function is used to substitute the data in the Vstr string with
       a pointer to a data array.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[7]), think of this function like
       doing a vstr_del() and then a vstr_add_ptr() (but it's atomic).

     Function:  vstr_sub_non()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t




Vstr 1.0.15                06-Mar-2006                         41





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Length of non data
       Type[4]: size_t

       Explanation:

         This  function is used to substitute the data in the Vstr string with
       "non" (or invisible) data.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[7]), think of this function like
       doing a vstr_del() and then a vstr_add_non() (but it's atomic).

     Function:  vstr_sub_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr memory reference
       Type[4]: struct Vstr_ref *

       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length of Vstr memory reference (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function is used to substitute the data in the Vstr string with
       a memory reference.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).




Vstr 1.0.15                06-Mar-2006                         42





vstr(3)                Vstr String Library                vstr(3)


       Note:

         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[7]), think of this function like
       doing a vstr_del() and then a vstr_add_ref() (but it's atomic).

     Function:  vstr_sub_vstr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Parameter[6]: Type for Vstr sub (VSTR_TYPE_SUB_*)
       Type[6]: unsigned int

       Explanation:

         This  function  is  used  to  substitute  the data in the Vstr string
       (Parameter[1]) with the data in another Vstr string (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[7]), think of this function like
       doing a vstr_del() and then a vstr_add_vstr() (but it's atomic).
         The  function  can  change  how  the data is added to the Vstr string
       (Parameter[1]) and in some cases even how the data  is  represented  in
       the  Vstr string (Parameter[3]) for more information see the documenta-
       tion on the VSTR_TYPE_SUB_* constants.

     Function:  vstr_sub_rep_chr()
       Returns: TRUE on success and FALSE on failure
       Type: int



Vstr 1.0.15                06-Mar-2006                         43





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Character to repeat
       Type[4]: char

       Parameter[5]: Number of times to repeat character (Parameter[3])
       Type[5]: size_t

       Explanation:

         This function is used to substitute the data in the Vstr string  with
       one or more copies of the character (Parameter[3]).
         Think  of  this  function  as  doing a memset() into data in the Vstr
       string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         The  function will return 0 if it needs to allocate memory and cannot
       do so, although if it does fail the Vstr string won't have changed (Ie.
       the function is atomic).

       Note:

         The length of the Vstr string (Parameter[3]) can be larger or smaller
       than the length of the data (Parameter[5]).
         Think  of  this  function  as  doing  a   vstr_del()   and   then   a
       vstr_add_rep_chr() (but it's atomic).
         If  the  length  of the data (Parameter[5]) is equal to the length of
       the Vstr string (Parameter[3]) and the data in the Vstr string is in  a
       BUF  node  then  the  data will just be overwritten (Ie. no allocations
       will happen).

     Function:  vstr_sub_cstr_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *




Vstr 1.0.15                06-Mar-2006                         44





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function calls vstr_sub_buf() with the length being the value of
       strlen() on the data parameter (Parameter[4]).

     Function:  vstr_sub_cstr_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This function calls vstr_sub_ptr() with the length being the value of
       strlen() on the data parameter (Parameter[4]).

     Function:  vstr_sub_cstr_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr memory reference
       Type[4]: struct Vstr_ref *

       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function calls vstr_sub_ref() with the length being the value of
       strlen()  on  the  memory from the Vstr memory reference (Parameter[3])
       starting at the offset (Parameter[4]).

     Function:  VSTR_SUB_CSTR_BUF()
       Returns: TRUE on success and FALSE on failure
       Type: int



Vstr 1.0.15                06-Mar-2006                         45





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_sub_buf() with the  length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SUB_CSTR_PTR()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  macro  function  calls vstr_sub_ptr() with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SUB_CSTR_REF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr memory reference
       Type[4]: struct Vstr_ref *




Vstr 1.0.15                06-Mar-2006                         46





vstr(3)                Vstr String Library                vstr(3)


       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Explanation:

         This macro function calls vstr_sub_ref() with the  length  being  the
       value of strlen() on the memory from the Vstr memory reference (Parame-
       ter[3]) starting at the offset (Parameter[4]).


Comparison of data functions
     Function:  vstr_cmp()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is used to compares the data in one Vstr string (Param-
       eter[1]) with data in another Vstr string (Parameter[4]) byte by  byte,
       all data is compared unsigned.
         Think of this function as doing a vstr_export_cstr_ptr() on each Vstr
       string, and then a call to memcmp() (although it doesn't allocate  any-
       thing).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         Data of type _NON is assumed to have the value -1, and  so  all  data
       compares as greater than it.

     Function:  vstr_cmp_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int



Vstr 1.0.15                06-Mar-2006                         47





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp().

     Function:  vstr_cmp_case()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is like vstr_cmp() but uppercase  and  lowercase  ASCII
       values compare equally with each other.

       Note:

         Data  of  type  _NON is assumed to have the value -1, and so all data
       compares as greater than it.

     Function:  vstr_cmp_case_buf()



Vstr 1.0.15                06-Mar-2006                         48





vstr(3)                Vstr String Library                vstr(3)


       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think  of  this  function as doing a vstr_dup_ptr() on the data array
       (Parameter[4]) and then calling vstr_cmp_case().

     Function:  vstr_cmp_fast()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  is  like vstr_cmp() but it is meant to provide "fast"
       results for use in internal comparisons (Ie. output is unlikely  to  be
       enjoyed by humans).

       Note:



Vstr 1.0.15                06-Mar-2006                         49





vstr(3)                Vstr String Library                vstr(3)


         Data  of  type  _NON is assumed to have the value -1, and so all data
       compares as greater than it.

     Function:  vstr_cmp_fast_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think  of  this  function as doing a vstr_dup_ptr() on the data array
       (Parameter[4]) and then calling vstr_cmp_fast().

     Function:  vstr_cmp_vers()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  is  used  to  compare  the  data  in  one Vstr string



Vstr 1.0.15                06-Mar-2006                         50





vstr(3)                Vstr String Library                vstr(3)


       (Parameter[1]) with data in another Vstr string (Parameter[4]), however
       for ASCII digits the algorithm tests on the numbers themselves (so "10"
       is greater than "9" but "01" is greater than "012", as  the  later  are
       fractions).
         Think of this function as doing a vstr_export_cstr_ptr() on each Vstr
       string, and then a call to strverscmp() (although it  doesn't  allocate
       anything, _and_ it deals with 0 bytes in the data).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         Data of type _NON is assumed to have the value -1, and  so  all  data
       compares as greater than it.

     Function:  vstr_cmp_vers_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_vers().

     Function:  vstr_cmp_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string



Vstr 1.0.15                06-Mar-2006                         51





vstr(3)                Vstr String Library                vstr(3)


       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  returns  !vstr_cmp()  if  both  of  the length values
       (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.

     Function:  vstr_cmp_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cmp_buf()  with  the length of the buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t




Vstr 1.0.15                06-Mar-2006                         52





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function returns !vstr_cmp_buf() if both of  the  length  values
       (Parameter[3] Parameter[5]) are equal, or FALSE otherwise.

     Function:  vstr_cmp_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  returns !vstr_cmp_buf(), if both of the length values
       are equal, with the length of the buffer being the value of strlen() on
       the data parameter (Parameter[4]).

     Function:  vstr_cmp_case_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  returns !vstr_cmp_case() if both of the length values
       (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.




Vstr 1.0.15                06-Mar-2006                         53





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_cmp_case_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_case_buf() with the length of the buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_case_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const void *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_case_buf() if both of the length val-
       ues (Parameter[3] Parameter[5]) are equal, or FALSE otherwise.

     Function:  vstr_cmp_case_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])



Vstr 1.0.15                06-Mar-2006                         54





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  returns  !vstr_cmp_case_buf(),  if both of the length
       values are equal, with the length of the  buffer  being  the  value  of
       strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_fast_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_fast_buf() with the length of the buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_vers_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t



Vstr 1.0.15                06-Mar-2006                         55





vstr(3)                Vstr String Library                vstr(3)


       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  returns !vstr_cmp_vers() if both of the length values
       (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.

     Function:  vstr_cmp_vers_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_vers_buf() with the length of the buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_vers_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const void *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_vers_buf() if both of the length val-
       ues (Parameter[3] Parameter[5]) are equal, or FALSE otherwise.




Vstr 1.0.15                06-Mar-2006                         56





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_cmp_vers_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  returns  !vstr_cmp_vers_buf(),  if both of the length
       values are equal, with the length of the  buffer  being  the  value  of
       strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_bod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp() with the both lengths as the lowest of
       either  passed  length (Parameter[3]) or (Parameter[6]). Thus you get a
       comparison of the beginning of the data in the two strings.

     Function:  vstr_cmp_eod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison



Vstr 1.0.15                06-Mar-2006                         57





vstr(3)                Vstr String Library                vstr(3)


       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp() with the both lengths as the lowest of
       either passed length (Parameter[3])  or  (Parameter[6])  and  with  the
       positions  (Parameter[3]) and (Parameter[6]) changed so that the length
       of each goes to the end of the string. Thus you get a comparison of the
       end of the data in the two strings.

     Function:  vstr_cmp_bod_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_bod().




Vstr 1.0.15                06-Mar-2006                         58





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_cmp_eod_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_eod().

     Function:  vstr_cmp_bod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_bod().

     Function:  vstr_cmp_eod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison



Vstr 1.0.15                06-Mar-2006                         59





vstr(3)                Vstr String Library                vstr(3)


       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_eod().

     Function:  vstr_cmp_bod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_bod_buf().

     Function:  vstr_cmp_eod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t



Vstr 1.0.15                06-Mar-2006                         60





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_eod_buf().

     Function:  vstr_cmp_bod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_bod_buf() with the length of the  buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_eod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:




Vstr 1.0.15                06-Mar-2006                         61





vstr(3)                Vstr String Library                vstr(3)


         This function calls vstr_cmp_eod_buf() with the length of the  buffer
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cmp_bod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cmp_bod_buf_eq()  with  the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_eod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cmp_eod_buf_eq()  with  the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_case_bod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *



Vstr 1.0.15                06-Mar-2006                         62





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp_case() with the both lengths as the low-
       est  of either passed length (Parameter[3]) or (Parameter[6]). Thus you
       get a comparison of the beginning of the data in the two strings.

     Function:  vstr_cmp_case_eod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp_case() with the both lengths as the low-
       est of either passed length (Parameter[3]) or (Parameter[6])  and  with
       the  positions  (Parameter[3])  and  (Parameter[6]) changed so that the
       length of each goes to the end of the string. Thus you get a comparison
       of the end of the data in the two strings.

     Function:  vstr_cmp_case_bod_eq()
       Returns: TRUE on success and FALSE on failure



Vstr 1.0.15                06-Mar-2006                         63





vstr(3)                Vstr String Library                vstr(3)


       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_case_bod().

     Function:  vstr_cmp_case_eod_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_case_eod().

     Function:  vstr_cmp_case_bod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int



Vstr 1.0.15                06-Mar-2006                         64





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_case_bod().

     Function:  vstr_cmp_case_eod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_case_eod().

     Function:  vstr_cmp_case_bod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t



Vstr 1.0.15                06-Mar-2006                         65





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_case_bod_buf().

     Function:  vstr_cmp_case_eod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_case_eod_buf().

     Function:  vstr_cmp_case_bod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:



Vstr 1.0.15                06-Mar-2006                         66





vstr(3)                Vstr String Library                vstr(3)


         This function calls vstr_cmp_case_bod_buf() with the  length  of  the
       buffer  being  the  value  of  strlen()  on the data parameter (Parame-
       ter[4]).

     Function:  vstr_cmp_case_eod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cmp_case_eod_buf() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_case_bod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_case_bod_buf_eq() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_case_eod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string



Vstr 1.0.15                06-Mar-2006                         67





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_case_eod_buf_eq() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_vers_bod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp_vers() with the both lengths as the low-
       est  of either passed length (Parameter[3]) or (Parameter[6]). Thus you
       get a comparison of the beginning of the data in the two strings.

     Function:  vstr_cmp_vers_eod()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         68





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function calls vstr_cmp_vers() with the both lengths as the low-
       est of either passed length (Parameter[3]) or (Parameter[6])  and  with
       the  positions  (Parameter[3])  and  (Parameter[6]) changed so that the
       length of each goes to the end of the string. Thus you get a comparison
       of the end of the data in the two strings.

     Function:  vstr_cmp_vers_bod_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_vers_bod().

     Function:  vstr_cmp_vers_eod_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string



Vstr 1.0.15                06-Mar-2006                         69





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function returns !vstr_cmp_vers_eod().

     Function:  vstr_cmp_vers_bod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_vers_bod().

     Function:  vstr_cmp_vers_eod_buf()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         70





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         Think of this function as doing a vstr_dup_ptr() on  the  data  array
       (Parameter[4]) and then calling vstr_cmp_vers_eod().

     Function:  vstr_cmp_vers_bod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_vers_bod_buf().

     Function:  vstr_cmp_vers_eod_buf_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string



Vstr 1.0.15                06-Mar-2006                         71





vstr(3)                Vstr String Library                vstr(3)


       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function returns !vstr_cmp_vers_eod_buf().

     Function:  vstr_cmp_vers_bod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_vers_bod_buf() with the  length  of  the
       buffer  being  the  value  of  strlen()  on the data parameter (Parame-
       ter[4]).

     Function:  vstr_cmp_vers_eod_cstr()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cmp_vers_eod_buf() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).



Vstr 1.0.15                06-Mar-2006                         72





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_cmp_vers_bod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_vers_bod_buf_eq() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  vstr_cmp_vers_eod_cstr_eq()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This function calls vstr_cmp_vers_eod_buf_eq() with the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  VSTR_CMP_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t




Vstr 1.0.15                06-Mar-2006                         73





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  macro function returns !vstr_cmp() if both of the length values
       (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.

     Function:  VSTR_CMP_CSTR()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This  macro  function  calls  vstr_cmp_buf()  with  the length of the
       buffer being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  VSTR_CMP_BUF_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data



Vstr 1.0.15                06-Mar-2006                         74





vstr(3)                Vstr String Library                vstr(3)


       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  macro  function  returns  !vstr_cmp_buf() if both of the length
       values (Parameter[3] Parameter[5]) are equal, or FALSE otherwise.

     Function:  VSTR_CMP_CSTR_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This macro function returns !vstr_cmp_buf(), if both  of  the  length
       values  are  equal,  with  the  length of the buffer being the value of
       strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CMP_CASE_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t




Vstr 1.0.15                06-Mar-2006                         75





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This macro function returns !vstr_cmp_case() if both  of  the  length
       values (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.

     Function:  VSTR_CMP_CASE_CSTR()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_cmp_case_buf() with the length of  the
       buffer  being  the  value  of  strlen()  on the data parameter (Parame-
       ter[4]).

     Function:  VSTR_CMP_CASE_BUF_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const void *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         This macro function  returns  !vstr_cmp_case_buf()  if  both  of  the
       length  values  (Parameter[3]  Parameter[5]) are equal, or FALSE other-
       wise.

     Function:  VSTR_CMP_CASE_CSTR_EQ()



Vstr 1.0.15                06-Mar-2006                         76





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This macro function returns  !vstr_cmp_case_buf(),  if  both  of  the
       length  values are equal, with the length of the buffer being the value
       of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CMP_VERS_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This macro function returns !vstr_cmp_vers() if both  of  the  length
       values (Parameter[3] Parameter[6]) are equal, or FALSE otherwise.

     Function:  VSTR_CMP_VERS_CSTR()
       Returns: Less then zero, zero or greater than zero depending on compar-
       ison
       Type: int

       Parameter[1]: Vstr string



Vstr 1.0.15                06-Mar-2006                         77





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_cmp_vers_buf() with the length of  the
       buffer  being  the  value  of  strlen()  on the data parameter (Parame-
       ter[4]).

     Function:  VSTR_CMP_VERS_BUF_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to ASCII C string
       Type[4]: const void *

       Parameter[5]: Length of ASCII C string (Parameter[4])
       Type[5]: size_t

       Explanation:

         This macro function  returns  !vstr_cmp_vers_buf()  if  both  of  the
       length  values  (Parameter[3]  Parameter[5]) are equal, or FALSE other-
       wise.

     Function:  VSTR_CMP_VERS_CSTR_EQ()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t



Vstr 1.0.15                06-Mar-2006                         78





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]: Pointer to ASCII C string
       Type[4]: const char *

       Explanation:

         This macro function returns  !vstr_cmp_vers_buf(),  if  both  of  the
       length  values are equal, with the length of the buffer being the value
       of strlen() on the data parameter (Parameter[4]).


Searching for data functions
     Function:  vstr_srch_chr_fwd()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Character to search for
       Type[4]: char

       Explanation:

         This function is used to search forward for a  character  in  a  Vstr
       string.
         Think  of this function as doing a vstr_export_cstr_ptr() on the Vstr
       string, and then a call to memchr() (although  it's  much  faster  than
       doing that and doesn't allocate anything).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the character cannot be found 0 is returned.

     Function:  vstr_srch_chr_rev()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Character
       Type[4]: char




Vstr 1.0.15                06-Mar-2006                         79





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to search reverse for a  character  in  a  Vstr
       string.
         Think  of this function as doing a vstr_export_cstr_ptr() on the Vstr
       string, and then a call to memrchr() (although it doesn't allocate any-
       thing).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the character cannot be found 0 is returned.

     Function:  vstr_srch_chrs_fwd()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to search forward for any of the characters  in
       the data array (Parameter[4]) in a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If any of the characters cannot be found 0 is returned.

     Function:  vstr_srch_chrs_rev()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *




Vstr 1.0.15                06-Mar-2006                         80





vstr(3)                Vstr String Library                vstr(3)


       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to search reverse for any of the characters  in
       the data array (Parameter[4]) in a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If any of the characters cannot be found 0 is returned.

     Function:  vstr_csrch_chrs_fwd()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to search forward for any of the characters not
       in the data array (Parameter[4]) in a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If any of the characters cannot be found 0 is returned.

     Function:  vstr_csrch_chrs_rev()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *




Vstr 1.0.15                06-Mar-2006                         81





vstr(3)                Vstr String Library                vstr(3)


       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to search reverse for any of the characters not
       in the data array (Parameter[4]) in a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If any of the characters cannot be found 0 is returned.

     Function:  vstr_srch_buf_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to search forward for  the  data  in  the  data
       array (Parameter[4]) in a Vstr string.
         Think  of this function as doing a vstr_export_cstr_ptr() on the Vstr
       string, and then a call to memmem() (although  it's  much  faster  than
       doing that and doesn't allocate anything).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

       Note:

         If the pointer to data (Parameter[4]) is NULL then _NON data  of  the
       specified size (Parameter[5]) will be searched for.

     Function:  vstr_srch_buf_rev()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])



Vstr 1.0.15                06-Mar-2006                         82





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  function  is  used  to  search reverse for the data in the data
       array (Parameter[4]) in a Vstr string.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       specified size (Parameter[5]) will be searched for.

     Function:  vstr_srch_vstr_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is used to search forward for  the  data  in  the  Vstr
       string (Parameter[4]) in the Vstr string (Parameter[1]).
         Think of this function as doing a vstr_export_cstr_ptr() on each Vstr
       string, and then a call to memmem() (although  it's  much  faster  than
       doing that and doesn't allocate anything).
         If the function can detect that the values of parameters are in error



Vstr 1.0.15                06-Mar-2006                         83





vstr(3)                Vstr String Library                vstr(3)


       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

     Function:  vstr_srch_vstr_rev()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is used to search reverse for  the  data  in  the  Vstr
       string (Parameter[4]) in the Vstr string (Parameter[1]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

     Function:  vstr_srch_case_chr_fwd()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Character to search for
       Type[4]: char

       Explanation:

         This function is the same as vstr_srch_chr_fwd()  but  uppercase  and
       lowercase ASCII values are treated equivalently.




Vstr 1.0.15                06-Mar-2006                         84





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_srch_case_chr_rev()
       Returns: Position in the Vstr string of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Character
       Type[4]: char

       Explanation:

         This  function  is  the same as vstr_srch_chr_rev() but uppercase and
       lowercase ASCII values are treated equivalently.

     Function:  vstr_srch_case_buf_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is the same as vstr_srch_buf_fwd()  but  uppercase  and
       lowercase ASCII values are treated equivalently.

       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       specified size (Parameter[5]) will be searched for.

     Function:  vstr_srch_case_buf_rev()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t




Vstr 1.0.15                06-Mar-2006                         85





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is the same as vstr_srch_buf_fwd()  but  uppercase  and
       lowercase ASCII values are treated equivalently.

       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       specified size (Parameter[5]) will be searched for.

     Function:  vstr_srch_case_vstr_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is the same as vstr_srch_vstr_fwd() but  uppercase  and
       lowercase ASCII values are treated equivalently.

     Function:  vstr_srch_case_vstr_rev()
       Returns: Position in the Vstr string of the start of the data



Vstr 1.0.15                06-Mar-2006                         86





vstr(3)                Vstr String Library                vstr(3)


       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr string
       Type[4]: const struct Vstr_base *

       Parameter[5]: Start position in the Vstr string (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length in the Vstr string (Parameter[4])
       Type[6]: size_t

       Explanation:

         This  function  is the same as vstr_srch_vstr_rev() but uppercase and
       lowercase ASCII values are treated equivalently.

     Function:  vstr_srch_cstr_buf_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This function calls vstr_srch_buf_fwd() with  the  length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_srch_cstr_buf_rev()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])



Vstr 1.0.15                06-Mar-2006                         87





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_srch_buf_rev()  with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_srch_cstr_chrs_fwd()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This function calls vstr_srch_chrs_fwd() with the  length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_srch_cstr_chrs_rev()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_srch_chrs_rev() with the length being the
       value of strlen() on the data parameter (Parameter[4]).



Vstr 1.0.15                06-Mar-2006                         88





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_csrch_cstr_chrs_fwd()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This function calls vstr_csrch_chrs_fwd() with the length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_csrch_cstr_chrs_rev()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  function  calls vstr_csrch_chrs_rev() with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_srch_case_cstr_buf_fwd()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t



Vstr 1.0.15                06-Mar-2006                         89





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This function calls vstr_srch_case_buf_fwd() with  the  length  being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_srch_case_cstr_buf_rev()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_srch_case_buf_rev() with the length being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CSTR_BUF_FWD()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_srch_buf_fwd() with the  length  being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CSTR_BUF_REV()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t




Vstr 1.0.15                06-Mar-2006                         90





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  macro  function calls vstr_srch_buf_rev() with the length being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CSTR_CHRS_FWD()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_srch_chrs_fwd() with the length  being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CSTR_CHRS_REV()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *




Vstr 1.0.15                06-Mar-2006                         91





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This  macro function calls vstr_srch_chrs_rev() with the length being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CSRCH_CSTR_CHRS_FWD()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_csrch_chrs_fwd() with the length being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CSRCH_CSTR_CHRS_REV()
       Returns: Position in the Vstr string of the start of the character
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_csrch_chrs_rev() with the length being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CASE_CSTR_BUF_FWD()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         92





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_srch_case_buf_fwd()  with  the  length
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SRCH_CASE_CSTR_BUF_REV()
       Returns: Position in the Vstr string of the start of the data
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  macro  function  calls vstr_srch_case_buf_rev() with the length
       being the value of strlen() on the data parameter (Parameter[4]).


Span of data calculation functions
     Function:  vstr_spn_bmap_eq_fwd()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Value to compare against in bytemap (Parameter[4])



Vstr 1.0.15                06-Mar-2006                         93





vstr(3)                Vstr String Library                vstr(3)


       Type[5]: unsigned char

       Explanation:

         This function is used to calculate the forward span  of  bytes,  that
       have the value (Parameter[5]) in the bytemap (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_spn_bmap_eq_rev()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Value to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This function is used to calculate the reverse span  of  bytes,  that
       have the value (Parameter[5]) in the bytemap (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_spn_bmap_and_fwd()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Bits to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char




Vstr 1.0.15                06-Mar-2006                         94





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to calculate the forward span  of  bytes,  that
       have  any bit set, in the value (Parameter[5]), in the bytemap (Parame-
       ter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_spn_bmap_and_rev()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Bits to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This  function  is  used to calculate the reverse span of bytes, that
       have any bit set, in the value (Parameter[5]), in the bytemap  (Parame-
       ter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_spn_chrs_fwd()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Parameter[5]: Length of spanning characters (Parameter[4])
       Type[5]: size_t




Vstr 1.0.15                06-Mar-2006                         95





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to calculate the forward span of characters  in
       the Vstr string that are in the data array.
         Think  of this function as doing a vstr_export_cstr_ptr() on the Vstr
       string, and then a call to strspn() (although  it's  much  faster  than
       doing  that  and doesn't allocate anything, _and_ it deals with 0 bytes
       in the data).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       size 1 will be looked for in the span.

     Function:  vstr_spn_chrs_rev()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Parameter[5]: Length of spanning characters (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to calculate the reverse span of characters  in
       the Vstr string that are in the data array.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         If the pointer to data (Parameter[4]) is NULL then _NON data  of  the
       size 1 will be looked for in the span.

     Function:  vstr_cspn_bmap_eq_fwd()
       Returns: Number of characters in the complement span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         96





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Value to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This  function  is  used  to calculate the forward complement span of
       bytes, that have the  value  (Parameter[5])  in  the  bytemap  (Parame-
       ter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_cspn_bmap_eq_rev()
       Returns: Number of characters in the complement span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Value to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This function is used to calculate the  reverse  complement  span  of
       bytes,  that  have  the  value  (Parameter[5])  in the bytemap (Parame-
       ter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_cspn_bmap_and_fwd()
       Returns: Number of characters in the complement span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         97





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Bits to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This  function  is  used  to calculate the forward complement span of
       bytes, that have any bit set,  in  the  value  (Parameter[5]),  in  the
       bytemap (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_cspn_bmap_and_rev()
       Returns: Number of characters in the complement span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to bytemap
       Type[4]: const unsigned char[256]

       Parameter[5]: Bits to compare against in bytemap (Parameter[4])
       Type[5]: unsigned char

       Explanation:

         This function is used to calculate the  reverse  complement  span  of
       bytes,  that  have  any  bit  set,  in the value (Parameter[5]), in the
       bytemap (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_cspn_chrs_fwd()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                         98





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Parameter[5]: Length of spanning characters (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  function is used to calculate the forward span of characters in
       the Vstr string that are in the compliment of those in the data  array.
         Think  of this function as doing a vstr_export_cstr_ptr() on the Vstr
       string, and then a call to strcspn() (although it's  much  faster  than
       doing  that  and doesn't allocate anything, _and_ it deals with 0 bytes
       in the data).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       size 1 will not be looked for in the span.

     Function:  vstr_cspn_chrs_rev()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Parameter[5]: Length of spanning characters (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is used to calculate the reverse span of characters  in
       the  Vstr string that are in the compliment of those in the data array.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.




Vstr 1.0.15                06-Mar-2006                         99





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If  the  pointer to data (Parameter[4]) is NULL then _NON data of the
       size 1 will not be looked for in the span.

     Function:  vstr_spn_cstr_chrs_fwd()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This function calls vstr_spn_chrs_fwd() with  the  length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_spn_cstr_chrs_rev()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_spn_chrs_rev()  with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cspn_cstr_chrs_fwd()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                        100





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This function calls vstr_cspn_chrs_fwd() with the  length  being  the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_cspn_cstr_chrs_rev()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_cspn_chrs_rev() with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SPN_CSTR_CHRS_FWD()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This function calls vstr_spn_chrs_fwd() with  the  length  being  the



Vstr 1.0.15                06-Mar-2006                        101





vstr(3)                Vstr String Library                vstr(3)


       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SPN_CSTR_CHRS_REV()
       Returns: Number of characters in the span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_spn_chrs_rev()  with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CSPN_CSTR_CHRS_FWD()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This macro function calls vstr_cspn_chrs_fwd() with the length  being
       the value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_CSPN_CSTR_CHRS_REV()
       Returns: Number of characters in the compliment span
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t




Vstr 1.0.15                06-Mar-2006                        102





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to spanning characters
       Type[4]: const char *

       Explanation:

         This  macro function calls vstr_cspn_chrs_rev() with the length being
       the value of strlen() on the data parameter (Parameter[4]).


Convertion of data functions
     Function:  vstr_conv_lowercase()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         This function converts all the uppercase ASCII characters into lower-
       case ASCII characters.

     Function:  vstr_conv_uppercase()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         This function converts all the lowercase ASCII characters into upper-
       case ASCII characters.

     Function:  vstr_conv_unprintable_chr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string



Vstr 1.0.15                06-Mar-2006                        103





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Flags starting VSTR_FLAG_CONV_UNPRINTABLE_*
       Type[4]: unsigned int

       Parameter[5]: Character to substitute in place of the unprintable char-
       acter
       Type[5]: char

       Explanation:

         This function substitutes all unprintable characters with the substi-
       tution character (Parameter[5]).

     Function:  vstr_conv_unprintable_del()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Flags starting VSTR_FLAG_CONV_UNPRINTABLE_*
       Type[4]: unsigned int

       Explanation:

         This function deletes all unprintable characters.

     Function:  vstr_conv_encode_uri()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:



Vstr 1.0.15                06-Mar-2006                        104





vstr(3)                Vstr String Library                vstr(3)


         This function converts characters to the URI %<hex><hex> encoding, so
       the ASCII space character ' ' becomes the encoded sequence %20 etc.

       Note:

         It  converts  all  the  characters  in  section 2.4.3 of rfc2396 into
       encoded form (that's all of the control, space, unwise and  high  ASCII
       characters).

     Function:  vstr_conv_decode_uri()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         This  function converts characters from the URI %<hex><hex> encoding,
       so that the encoded sequence %20 becomes the ASCII space character '  '
       etc.


Section of Vstr string functions
     Function:  VSTR_SECTS_DECL()
       Returns: Declaration of a Vstr sections
       Type: struct Vstr_sects *

       Parameter[1]: Name of variable to declare
       Type[1]: <symbol>

       Parameter[2]: Maximum size of the Vstr sections (Parameter[1])
       Type[2]: unsigned int

       Explanation:

         This  macro  function declares a Vstr sections, of the specified size
       (Parameter[2]).

       Note:

         VSTR_SECTS_DECL_INIT() needs to be called on the Vstr sections before
       it can be used.

     Function:  VSTR_SECTS_EXTERN_DECL()
       Returns: Extern declaration of a Vstr sections
       Type: struct Vstr_sects *




Vstr 1.0.15                06-Mar-2006                        105





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Name of variable to declare
       Type[1]: <symbol>

       Parameter[2]: Maximum size of the Vstr sections
       Type[2]: unsigned int

       Explanation:

         This  macro  function declares a Vstr sections, of the specified size
       (Parameter[2]), that is usable after an extern keyword.

     Function:  VSTR_SECTS_DECL_INIT()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Explanation:

         This macro function finishes initializing a Vstr  sections  that  has
       been allocated using VSTR_SECTS_DECL().
         This  macro function can be called multiple times without causing any
       problems.

     Function:  VSTR_SECTS_INIT()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Parameter[2]: Maximum number of the Vstr sections
       Type[2]: unsigned int

       Parameter[3]: Array of Vstr section nodes
       Type[3]: struct Vstr_sect_node *

       Parameter[4]: Non-zero if the nodes (Parameter[3])  can  be  passed  to
       free()
       Type[4]: int

       Explanation:

         The macro function initializes a self declared Vstr sections.

       Note:

         Unlike  VSTR_SECTS_DECL_INIT()  this  should  only be called once per
       initialization.

     Function:  VSTR_SECTS_NUM()
       Returns: The ith Vstr section node in the Vstr sections
       Type: struct Vstr_sect_node *



Vstr 1.0.15                06-Mar-2006                        106





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Parameter[2]: Number of the section in the Vstr sections (Parameter[1])
       Type[2]: unsigned int

       Explanation:

         Simple way to goto the Vstr section node in a Vstr sections.

     Function:  vstr_sects_make()
       Returns: Vstr sections
       Type: struct Vstr_sects *

       Parameter[1]: Maximum number of the Vstr sections
       Type[1]: unsigned int

       Explanation:

         This function will make a Vstr sections, or return NULL.

     Function:  vstr_sects_free()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Explanation:

         This   function   will   free   a   Vstr   sections,   allocated   by
       vstr_sects_make().

     Function:  vstr_sects_add()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Parameter[2]: Position in a Vstr string
       Type[2]: size_t

       Parameter[3]: Length in a Vstr string
       Type[3]: size_t

       Explanation:

         This function will add the position and length to a Vstr section node
       at  the end of the Vstr sections (Parameter[1]). If space is not avail-
       able and (Parameter[1])->can_add_sz is TRUE, then space try to be allo-
       cated.

     Function:  vstr_sects_del()



Vstr 1.0.15                06-Mar-2006                        107





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Parameter[2]: Number of the section in the Vstr sections (Parameter[1])
       Type[2]: unsigned int

       Explanation:

         This function will delete a specified Vstr section node. If  (Parame-
       ter[1])->can_del_sz is TRUE then space may be compacted.

     Function:  vstr_sects_foreach()
       Returns: Number of the times the foreach function ran the callback
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Vstr sections
       Type[2]: struct Vstr_sects *

       Parameter[3]: Flags starting VSTR_FLAG_SECT_FOREACH_*
       Type[3]: unsigned int

       Parameter[4]: Function to run as foreach body
       Type[4]: unsigned int (*)(const Vstr_base *, size_t, size_t, void *)

       Parameter[5]: Data to pass to foreach body function (Parameter[4])
       Type[5]: void *

       Explanation:

         This  function  will  run the foreach body function (Parameter[4]) on
       every valid Vstr section node in the Vstr sections.
         The callback  function  (Parameter[4])  is  passed  the  Vstr  string
       (Parameter[1]),  the  position and length from the current Vstr section
       node and finally the caller supplied data (Parameter[5]).

       Note:

         The  foreach  callback   body   function   returns   types   starting
       VSTR_TYPE_SECT_FOREACH_.

     Function:  vstr_sects_update_add()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Vstr sections



Vstr 1.0.15                06-Mar-2006                        108





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: struct Vstr_sects *

       Explanation:

         This  function will cause the section (Parameter[2]) to automatically
       be updated when changes are made to the Vstr string (Parameter[1]).

       Note:

         You need to call vstr_sects_update_del(), before you free the section
       (Parameter[2]).  However  if the next thing you are going to do is call
       vstr_free_base() on the Vstr string (Parameter[1]),  then  nothing  bad
       will happen if you call them in the oposite order.
         This uses the vstr_cache_add() function.

     Function:  vstr_sects_update_del()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Vstr sections
       Type[2]: struct Vstr_sects *

       Explanation:

         This  function  will cause the section (Parameter[2]) that was previ-
       ously updated when changes are made to the Vstr  string  (Parameter[1])
       to not be updated anymore.

     Function:  vstr_sects_srch()
       Returns: Number of the section in the Vstr sections (Parameter[1])
       Type: unsigned int

       Parameter[1]: Vstr sections
       Type[1]: struct Vstr_sects *

       Parameter[2]: Position in a Vstr string
       Type[2]: size_t

       Parameter[3]: Length in a Vstr string
       Type[3]: size_t

       Explanation:

         This  function  will search for the first Vstr section node in a Vstr
       section (Parameter[1]) that matches the position and length.


Splitting data into sections functions
     Function:  vstr_split_buf()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int



Vstr 1.0.15                06-Mar-2006                        109





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data to split on
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Vstr sections
       Type[6]: struct Vstr_sects *

       Parameter[7]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[7]: unsigned int

       Parameter[8]: Flags starting VSTR_FLAG_SPLIT_*
       Type[8]: unsigned int

       Explanation:

         This function is used to add  section  nodes  to  the  Vstr  sections
       (Parameter[6])  about the Vstr string (Parameter[1]). The function will
       add one section before each occurrence of the data (Parameter[4]),  and
       one final section for the rest of the Vstr string.
         If  the  limit  (Parameter[7])  is non-zero then ((Parameter[7]) - 1)
       occurrences of the data will be searched for and one final section will
       be  added  for  the rest of the Vstr string. This means that "a:b:c" if
       split on ":" with a limit of 2 will split into "a" and "b:c", and  that
       "a::" if split on ":" with a limit of 2 will split into "a" and ":".

     Function:  vstr_split_chrs()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to characters to split on
       Type[4]: const char *

       Parameter[5]: Length of characters (Parameter[4])
       Type[5]: size_t



Vstr 1.0.15                06-Mar-2006                        110





vstr(3)                Vstr String Library                vstr(3)


       Parameter[6]: Vstr sections
       Type[6]: struct Vstr_sects *

       Parameter[7]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[7]: unsigned int

       Parameter[8]: Flags starting VSTR_FLAG_SPLIT_
       Type[8]: unsigned int

       Explanation:

         This function works like vstr_split_buf() except that instead of hav-
       ing to match all the data in the data buffer  it  matches  any  of  the
       characters in the character buffer (Parameter[4]).

     Function:  vstr_split_cstr_buf()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data to split on
       Type[4]: const char *

       Parameter[5]: Vstr sections
       Type[5]: struct Vstr_sects *

       Parameter[6]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[6]: unsigned int

       Parameter[7]: Flags starting VSTR_FLAG_SPLIT_*
       Type[7]: unsigned int

       Explanation:

         This  function calls vstr_split_buf() with the length being the value
       of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_split_cstr_chrs()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t



Vstr 1.0.15                06-Mar-2006                        111





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to characters to split on
       Type[4]: const char *

       Parameter[5]: Vstr sections
       Type[5]: struct Vstr_sects *

       Parameter[6]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[6]: unsigned int

       Parameter[7]: Flags starting VSTR_FLAG_SPLIT_*
       Type[7]: unsigned int

       Explanation:

         This function calls vstr_split_chrs() with the length being the value
       of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SPLIT_CSTR_BUF()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to data to split on
       Type[4]: const char *

       Parameter[5]: Vstr sections
       Type[5]: struct Vstr_sects *

       Parameter[6]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[6]: unsigned int

       Parameter[7]: Flags starting VSTR_FLAG_SPLIT_*
       Type[7]: unsigned int

       Explanation:

         This  macro function calls vstr_split_buf() with the length being the
       value of strlen() on the data parameter (Parameter[4]).

     Function:  VSTR_SPLIT_CSTR_CHRS()
       Returns: Number of Vstr section nodes added to the Vstr sections
       Type: unsigned int




Vstr 1.0.15                06-Mar-2006                        112





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Pointer to characters to split on
       Type[4]: const char *

       Parameter[5]: Vstr sections
       Type[5]: struct Vstr_sects *

       Parameter[6]: Limit of sections to add to Vstr sections (Parameter[6])
       Type[6]: unsigned int

       Parameter[7]: Flags starting VSTR_FLAG_SPLIT_*
       Type[7]: unsigned int

       Explanation:

         This macro function calls vstr_split_chrs() with the length being the
       value of strlen() on the data parameter (Parameter[4]).


Parsing data functions
     Function:  vstr_parse_num()
       Returns: Data returned from callback function
       Type: void *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:   Base   to   parse   number   in   and   flags  starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Parameter[7]: Function to run as parse body
       Type[7]: void *(*)(unsigned int, int, unsigned int *, void *)




Vstr 1.0.15                06-Mar-2006                        113





vstr(3)                Vstr String Library                vstr(3)


       Parameter[8]: Data to pass to parse number callback  function  (Parame-
       ter[7])
       Type[8]: void *

       Explanation:

         This  function will parse a number, and pass it piece by piece to the
       callback function (Parameter[7]).
         The callback function (Parameter[7]) is passed the base and the value
       of  the  current piece of the number, the pointer to a valid error code
       and finally the caller supplied data (Parameter[8]).

       Note:

         If NULL is returned from the callback  function,  then  parsing  will
       stop at that point and immediately return.
         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_short()
       Returns: Number parsed from Vstr string
       Type: short

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This function will parse a number, in the range SHRT_MIN to SHRT_MAX,
       from the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,



Vstr 1.0.15                06-Mar-2006                        114





vstr(3)                Vstr String Library                vstr(3)


       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_ushort()
       Returns: Number parsed from Vstr string
       Type: unsigned short

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function will parse a number, in the range 0 to USHRT_MAX, from
       the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_int()
       Returns: Number parsed from Vstr string
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t




Vstr 1.0.15                06-Mar-2006                        115





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function  will parse a number, in the range INT_MIN to INT_MAX,
       from the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_uint()
       Returns: Number parsed from Vstr string
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function  will parse a number, in the range 0 to UINT_MAX, from
       the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).




Vstr 1.0.15                06-Mar-2006                        116





vstr(3)                Vstr String Library                vstr(3)


       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_long()
       Returns: Number parsed from Vstr string
       Type: long

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This function will parse a number, in the range LONG_MIN to LONG_MAX,
       from the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_ulong()
       Returns: Number parsed from Vstr string
       Type: unsigned long

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t




Vstr 1.0.15                06-Mar-2006                        117





vstr(3)                Vstr String Library                vstr(3)


       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function will parse a number, in the range 0 to ULONG_MAX, from
       the start of a Vstr string.
         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.

     Function:  vstr_parse_intmax()
       Returns: Number parsed from Vstr string
       Type: intmax_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:  Base   to   parse   number   in   and   flags   starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function  will  parse a number, in the range INTMAX_MIN to INT-
       MAX_MAX, from the start of a Vstr string.



Vstr 1.0.15                06-Mar-2006                        118





vstr(3)                Vstr String Library                vstr(3)


         The base that the number is parsed as is passed by specifying a  num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.
         If the intmax_t type is unavailable on the platform, then this  func-
       tion will act the same as vstr_parse_long().

     Function:  vstr_parse_uintmax()
       Returns: Number parsed from Vstr string
       Type: uintmax_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]:   Base   to   parse   number   in   and   flags  starting
       VSTR_FLAG_PARSE_NUM_
       Type[4]: unsigned int

       Parameter[5]: Returns length of number (Return)
       Type[5]: size_t *

       Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
       Type[6]: unsigned int *

       Explanation:

         This function will parse a number, in the  range  0  to  UINTMAX_MAX,
       from the start of a Vstr string.
         The  base that the number is parsed as is passed by specifying a num-
       ber between 2 and 36 as part of the flags (Parameter[4]).

       Note:

         A base of 0 specifies that the base should be automatically detected,
       by choosing base 16 if the number starts 0x or 0X, base 2 if the number
       starts 0b or 0B, base 8 if the number starts with a 0 and defaulting to
       base 10 otherwise.
         If  the intmax_t type is unavailable on the platform, then this func-
       tion will act the same as vstr_parse_ulong().

     Function:  vstr_parse_netstr()
       Returns: Returns the length of the netstring
       Type: size_t



Vstr 1.0.15                06-Mar-2006                        119





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Returns the position of the start of the netstring data
       Type[4]: size_t *

       Parameter[5]: Returns the length of the data in the netstring
       Type[5]: size_t *

       Explanation:

         This function is used to search forward for the beginning of  a  net-
       string in the Vstr string (Parameter[4]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

       Note:

         The netstring is only found if it is "whole", in that the entire net-
       string  and  data  exist in the Vstr string. If one is found but is not
       whole then the position of the start of data and the length of the net-
       string will still be returned.

     Function:  vstr_parse_netstr2()
       Returns: Position in the Vstr string of the start of the netstring2
       Type: size_t

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Returns the position of the start of the netstring data
       Type[4]: size_t *

       Parameter[5]: Returns the length of the netstring
       Type[5]: size_t *

       Explanation:

         This  function  is used to search forward for the beginning of a net-
       string in the Vstr string (Parameter[4]).
         If the function can detect that the values of parameters are in error



Vstr 1.0.15                06-Mar-2006                        120





vstr(3)                Vstr String Library                vstr(3)


       the function will return 0 to indicate an error.
         If the data cannot be found 0 is returned.

       Note:

         The netstring is only found if it is "whole", in that the entire net-
       string and data exist in the Vstr string. If one is found  but  is  not
       whole then the position of the start of data and the length of the net-
       string will still be returned.
         The specification of a netstring2 is a superset of the  specification
       of a netstring, so this function will find either.

     Function:  vstr_parse_ipv4()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Returns ip in array elements 0 to 3
       Type[4]: unsigned char *

       Parameter[5]: Returns CIDR mask, if requested
       Type[5]: unsigned int *

       Parameter[6]: Flags starting VSTR_FLAG_PARSE_IPV4_*
       Type[6]: unsigned int

       Parameter[7]: Returns length of parsed ip address (Parameter[4] Parame-
       ter[5])
       Type[7]: size_t *

       Parameter[8]: Returns error code starting VSTR_TYPE_PARSE_IPV4_ERR_
       Type[8]: unsigned int *

       Explanation:

         This function will parse an  ipv4  address,  or  optionally  an  ipv4
       address and a CIDR mask / netmask, from the Vstr string.

     Function:  vstr_parse_ipv6()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])



Vstr 1.0.15                06-Mar-2006                        121





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Returns ip in array elements 0 to 7
       Type[4]: unsigned int *

       Parameter[5]: Returns CIDR mask
       Type[5]: unsigned int *

       Parameter[6]: Flags starting VSTR_FLAG_PARSE_IPV6_*
       Type[6]: unsigned int

       Parameter[7]: Returns length of parsed ip address (Parameter[4] Parame-
       ter[5])
       Type[7]: size_t *

       Parameter[8]: Returns error code starting VSTR_TYPE_PARSE_IPV6_ERR_
       Type[8]: unsigned int *

       Explanation:

         This function will parse an  ipv6  address,  or  optionally  an  ipv6
       address and a CIDR mask, from the Vstr string.


Custom formatter functions
     Function:  vstr_fmt_add()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Parameter[3]: Function to use as callback from vstr_add_vfmt()
       Type[3]: int (*)(struct Vstr_base *, size_t, struct Vstr_fmt_spec *)

       Parameter[4]:  List  of  VSTR_TYPE_FMT_*  types  for  format  specifier
       (Parameter[2])
       Type[4]: ...

       Explanation:

         This function allows you to register arbitrary format specifiers  for
       printing  from  vstr_add_fmt().  Note  that  these trigger off the user
       escape character, which may or may not be  the  same  as  the  "system"
       escape character of '%'.
         The  call back you register should return 0 (zero) if memory couldn't
       be allocated and 1 (one) otherwise.




Vstr 1.0.15                06-Mar-2006                        122





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         If  the  user  escape  character is '%', then you can override system
       specifiers by using a specifier name (Parameter[2]) of  "i"  etc.  This
       isn't  recommended,  but  is  done so that you can have specifier names
       like "igloo" and it not be taken as a system specifier, however if  you
       then  did  "%igoo" that would be interpreted as a "%i" (int) specifica-
       tion followed by the string "goo".
         You can register multiple names with one callback, so you can  regis-
       ter  say  "{Vstr}"  and "{Vstr:%p%zu%zu%u}" ... the latter, with a user
       escape != '%', will do the right  thing  with  current  printf  warning
       checks  in gcc. We can all hope that the former will be as usable even-
       tually.
         If you register all your custom formatter names starting with one  of
       "{",  "[",  "<" or "("  and ending with one of "}", "]", ">" or ")" and
       no other instances of those characters ... then matching custom format-
       ters will be much faster.

     Function:  vstr_fmt_del()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function allows you to unregister a format specifier added using
       vstr_fmt_add().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_fmt_srch()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  allows you to find out if a format specifier has been
       added using vstr_fmt_add().



Vstr 1.0.15                06-Mar-2006                        123





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  VSTR_FMT_CB_ARG_PTR()
       Returns: Pointer to data
       Type: void *

       Parameter[1]: Format specifier passed to a callback of vstr_add_vfmt()
       Type[1]: struct Vstr_fmt_spec *

       Parameter[2]: Number of the parameter passed to the callback
       Type[2]: size_t

       Explanation:

         This  macro  function returns the nth (Parameter[2]) parameter passed
       to a callback of vstr_add_vfmt(), as a generic pointer.

     Function:  VSTR_FMT_CB_ARG_VAL()
       Returns: Data of specified type
       Type: Parameter[2]

       Parameter[1]: Format specifier passed to a callback of vstr_add_vfmt()
       Type[1]: struct Vstr_fmt_spec *

       Parameter[2]: Type of the specified value
       Type[2]: <symbol>

       Parameter[3]: Number of the parameter for the callback
       Type[3]: size_t

       Explanation:

         This macro function returns the nth (Parameter[3])  parameter  passed
       to a callback of vstr_add_vfmt(), by value.


Short cut helper functions
     Function:  vstr_sc_bmap_init_eq_spn_buf()
       Returns: Nothing
       Type: void

       Parameter[1]: Pointer to bytemap
       Type[1]: const unsigned char[256]

       Parameter[2]: Pointer to data
       Type[2]: const void *

       Parameter[3]: Length of a data (Parameter[2])
       Type[3]: size_t

       Parameter[4]: Value to set in bytemap (Parameter[4])



Vstr 1.0.15                06-Mar-2006                        124





vstr(3)                Vstr String Library                vstr(3)


       Type[4]: unsigned char

       Explanation:

         This  function  is  used  to  set  all the bytes in the data (Parame-
       ter[2]), to the value (Parameter[4]) in the bytemap (Parameter[1]).

     Function:  vstr_sc_bmap_init_eq_spn_cstr()
       Returns: Nothing
       Type: void

       Parameter[1]: Pointer to bytemap
       Type[1]: const unsigned char[256]

       Parameter[2]: Pointer to data
       Type[2]: const char *

       Parameter[3]: Value to set in bytemap (Parameter[4])
       Type[3]: unsigned char

       Explanation:

         This function calls vstr_sc_bmap_init_eq_spn_buf()  with  the  length
       being the value of strlen() on the data parameter (Parameter[2]).

     Function:  vstr_sc_bmap_init_or_spn_buf()
       Returns: Nothing
       Type: void

       Parameter[1]: Pointer to bytemap
       Type[1]: const unsigned char[256]

       Parameter[2]: Pointer to data
       Type[2]: const void *

       Parameter[3]: Length of a data (Parameter[2])
       Type[3]: size_t

       Parameter[4]: Value of bits to set in bytemap (Parameter[1])
       Type[4]: unsigned char

       Explanation:

         This  function  is  used  to  set  all the bytes in the data (Parame-
       ter[2]), to the value (Parameter[4]) combined with the original  value,
       in the bytemap (Parameter[1]).

     Function:  vstr_sc_bmap_init_or_spn_cstr()
       Returns: Nothing
       Type: void

       Parameter[1]: Pointer to bytemap
       Type[1]: const unsigned char[256]




Vstr 1.0.15                06-Mar-2006                        125





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Pointer to data
       Type[2]: const char *

       Parameter[3]: Value of bits to set in bytemap (Parameter[1])
       Type[3]: unsigned char

       Explanation:

         This  function  calls  vstr_sc_bmap_init_or_spn_buf() with the length
       being the value of strlen() on the data parameter (Parameter[2]).

     Function:  vstr_sc_posdiff()
       Returns: Length of difference between two positions
       Type: size_t

       Parameter[1]: Start position in a Vstr string
       Type[1]: size_t

       Parameter[2]: End position in a Vstr string
       Type[2]: size_t

       Explanation:

         This function is used to find the length between two positions inclu-
       sive.

     Function:  VSTR_SC_POSDIFF()
       Returns: Length of difference between two positions
       Type: size_t

       Parameter[1]: Start position in a Vstr string
       Type[1]: size_t

       Parameter[2]: End position in a Vstr string
       Type[2]: size_t

       Explanation:

         This  macro function is used to find the length between two positions
       inclusive.

     Function:  vstr_sc_poslast()
       Returns: Last position of the given start and length
       Type: size_t

       Parameter[1]: Start position in a Vstr string
       Type[1]: size_t

       Parameter[2]: Length of a Vstr string
       Type[2]: size_t

       Explanation:

         This function is used to find the last poition, given a position  and



Vstr 1.0.15                06-Mar-2006                        126





vstr(3)                Vstr String Library                vstr(3)


       a length (it's basically the oposite of vstr_sc_posdiff()).

     Function:  VSTR_SC_POSLAST()
       Returns: Last position of the given start and length
       Type: size_t

       Parameter[1]: Start position in a Vstr string
       Type[1]: size_t

       Parameter[2]: Length of a Vstr string
       Type[2]: size_t

       Explanation:

         This  macro  function is used to find the last poition, given a posi-
       tion and a length (it's basically the oposite of VSTR_SC_POSDIFF()).

     Function:  vstr_sc_reduce()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Length to reduce the Vstr string (Parameter[1])
       Type[4]: size_t

       Explanation:

         This function is a helper function to reduce the Vstr string  to  the
       desired length (Ie. delete by a given ammount from the end of the given
       Vstr string).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_sc_basename()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t




Vstr 1.0.15                06-Mar-2006                        127





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]: Position of basename (Return)
       Type[4]: size_t *

       Parameter[5]: Length of basename (Return)
       Type[5]: size_t *

       Explanation:

         This  function is a helper function to return the basename of a path.
       Unlike other implementations of this function nothing is allocated  and
       altered in the original string

       Note:

         This function, with vstr_sc_dirname(), always returns values that can
       be combined to generate the original path. This means that  this  func-
       tion will return an empty length for the path "/".

     Function:  vstr_sc_add_grpbasenum_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  function  is a helper function to output a number with the Vstr
       strings locale grouping characters, for a specific base.
         If copies both user data and locale data.
     Function:  vstr_sc_add_grpbasenum_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int



Vstr 1.0.15                06-Mar-2006                        128





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]: Pointer to data
       Type[4]: const void *

       Parameter[5]: Length of data (Parameter[4])
       Type[5]: size_t

       Explanation:

         This function is a helper function to output a number with  the  Vstr
       strings locale grouping characters, for a specific base.
         If  uses  pointers  for  the  user data and memory references for the
       locale data.

     Function:  vstr_sc_add_grpbasenum_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: Vstr_ref *

       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Parameter[6]: Length of Vstr memory reference (Parameter[4])
       Type[6]: size_t

       Explanation:

         This function is a helper function to output a number with  the  Vstr
       strings locale grouping characters, for a specific base.
         If uses memory references for the user data and the locale data.

     Function:  vstr_sc_add_grpnum_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const void *




Vstr 1.0.15                06-Mar-2006                        129





vstr(3)                Vstr String Library                vstr(3)


       Parameter[4]: Length of data (Parameter[3])
       Type[4]: size_t

       Explanation:

         This  function  is a helper function to output a number with the Vstr
       strings locale grouping characters.
         If copies both user data and locale data.

       Note:

         This function always uses the default locale information, if you have
       setup     specific     number    base    locale    information    using
       VSTR_CNTL_CONF_GET_LOC_REF_*  etc.  then  you'll  want   to   use   the
       vstr_sc_add_grpbasenum_* functions.

     Function:  vstr_sc_add_cstr_grpbasenum_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  function  calls  vstr_sc_add_grpbasenum_buf()  with  the length
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_sc_add_cstr_grpbasenum_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:



Vstr 1.0.15                06-Mar-2006                        130





vstr(3)                Vstr String Library                vstr(3)


         This function  calls  vstr_sc_add_grpbasenum_ptr()  with  the  length
       being the value of strlen() on the data parameter (Parameter[4]).

     Function:  vstr_sc_add_cstr_grpbasenum_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: Vstr_ref *

       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  function  calls  vstr_sc_add_grpbasenum_ref()  with  the length
       being the value of strlen() on memory from the  Vstr  memory  reference
       (Parameter[4]) starting at offset (Parameter[5]).

     Function:  VSTR_SC_ADD_CSTR_GRPBASENUM_BUF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  macro  function  calls  vstr_sc_add_grpbasenum_buf()  with  the
       length being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  VSTR_SC_ADD_CSTR_GRPBASENUM_PTR()
       Returns: TRUE on success and FALSE on failure
       Type: int




Vstr 1.0.15                06-Mar-2006                        131





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: const char *

       Explanation:

         This  macro  function  calls  vstr_sc_add_grpbasenum_ptr()  with  the
       length being the value of  strlen()  on  the  data  parameter  (Parame-
       ter[4]).

     Function:  VSTR_SC_ADD_CSTR_GRPBASENUM_REF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Base of the number in the data
       Type[3]: unsigned int

       Parameter[4]: Pointer to data
       Type[4]: Vstr_ref *

       Parameter[5]: Offset of Vstr memory reference (Parameter[4])
       Type[5]: size_t

       Explanation:

         This  macro  function  calls  vstr_sc_add_grpbasenum_ref()  with  the
       length being the value of strlen() on memory from the Vstr memory  ref-
       erence (Parameter[4]) starting at offset (Parameter[5]).

     Function:  vstr_sc_add_cstr_grpnum_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Pointer to data



Vstr 1.0.15                06-Mar-2006                        132





vstr(3)                Vstr String Library                vstr(3)


       Type[3]: const char *

       Explanation:

         This  function  calls  vstr_sc_add_grpnum_buf() with the length being
       the value of strlen() on the data parameter (Parameter[3]).

       Note:

         This function always uses the default locale information, if you have
       setup     specific     number    base    locale    information    using
       VSTR_CNTL_CONF_GET_LOC_REF_*  etc.  then  you'll  want   to   use   the
       vstr_sc_add_grpbasenum_* functions.

     Function:  VSTR_SC_ADD_CSTR_GRPNUM_BUF()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Pointer to data
       Type[3]: const char *

       Explanation:

         This  macro  function  calls vstr_sc_add_grpnum_buf() with the length
       being the value of strlen() on the data parameter (Parameter[3]).

       Note:

         This macro always uses the default locale information,  if  you  have
       setup     specific     number    base    locale    information    using
       VSTR_CNTL_CONF_GET_LOC_REF_*  etc.  then  you'll  want   to   use   the
       vstr_sc_add_grpbasenum_* functions.

     Function:  vstr_sc_conv_num_uint()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: unsigned int

       Parameter[4]: Pointer to array of numbers in the current base
       Type[4]: const char *



Vstr 1.0.15                06-Mar-2006                        133





vstr(3)                Vstr String Library                vstr(3)


       Parameter[5]: Base to convert number in
       Type[5]: unsigned int

       Explanation:

         This  function  will convert a number (Parameter[3]) into an array of
       bytes, the number is converted by using the byte at the offset  in  the
       array of numbers (Parameter[4]).

     Function:  vstr_sc_conv_num10_uint()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: unsigned int

       Explanation:

         This  function  will convert a number (Parameter[3]) into an array of
       numbers, in base 10, return value is the number of numbers written.

     Function:  vstr_sc_conv_num_ulong()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: unsigned int

       Parameter[4]: Pointer to array of numbers in the current base
       Type[4]: const char *

       Parameter[5]: Base to convert number in
       Type[5]: unsigned long

       Explanation:

         This function will convert a number (Parameter[3]) into an  array  of
       bytes,  the  number is converted by using the byte at the offset in the
       array of numbers (Parameter[4]).

     Function:  vstr_sc_conv_num10_ulong()
       Returns: Number of bytes written to (Parameter[1])



Vstr 1.0.15                06-Mar-2006                        134





vstr(3)                Vstr String Library                vstr(3)


       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: unsigned long

       Explanation:

         This function will convert a number (Parameter[3]) into an  array  of
       numbers, in base 10, return value is the number of numbers written.

     Function:  vstr_sc_conv_num_size()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: size_t

       Parameter[4]: Pointer to array of numbers in the current base
       Type[4]: const char *

       Parameter[5]: Base to convert number in
       Type[5]: unsigned int

       Explanation:

         This  function  will convert a number (Parameter[3]) into an array of
       bytes, the number is converted by using the byte at the offset  in  the
       array of numbers (Parameter[4]).

     Function:  vstr_sc_conv_num10_size()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: size_t




Vstr 1.0.15                06-Mar-2006                        135





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This  function  will convert a number (Parameter[3]) into an array of
       numbers, in base 10, return value is the number of numbers written.

     Function:  vstr_sc_conv_num_uintmax()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: uintmax_t

       Parameter[4]: Pointer to array of numbers in the current base
       Type[4]: const char *

       Parameter[5]: Base to convert number in
       Type[5]: unsigned int

       Explanation:

         This function will convert a number (Parameter[3]) into an  array  of
       bytes,  the  number is converted by using the byte at the offset in the
       array of numbers (Parameter[4]).

     Function:  vstr_sc_conv_num10_uintmax()
       Returns: Number of bytes written to (Parameter[1])
       Type: size_t

       Parameter[1]: Data array to export to
       Type[1]: char *

       Parameter[2]: Length of data (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Number to output
       Type[3]: uintmax_t

       Explanation:

         This function will convert a number (Parameter[3]) into an  array  of
       numbers, in base 10, return value is the number of numbers written.

     Function:  vstr_sc_dirname()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *



Vstr 1.0.15                06-Mar-2006                        136





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr
       Type[2]: size_t

       Parameter[3]: Length from position in the Vstr
       Type[3]: size_t

       Parameter[4]: Length of dirname (Return)
       Type[4]: size_t *

       Explanation:

         This function is a helper function to return the directory of a path,
       excluding the basename. Unlike other implementations of  this  function
       nothing is allocated and nothing is altered in the original string.

       Note:

         This  function,  with  vstr_sc_basename(), always returns values that
       can be combined to generate the original path.  This  means  that  this
       function  will  return  an  empty length for a relative filename in the
       current directory.

     Function:  vstr_sc_fmt_cb_beg()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Position in the Vstr string (Parameter[1]),  updated  for
       padding.
       Type[2]: size_t *

       Parameter[3]: Format specifier passed to a callback of vstr_add_vfmt()
       Type[3]: struct Vstr_fmt_spec *

       Parameter[4]:  Length of data you are going to add, updated due to pre-
       cision.
       Type[4]: size_t *

       Parameter[5]: Flags starting VSTR_FLAG_SC_FMT_CB_BEG_*
       Type[5]: unsigned int

       Explanation:

         This function is a helper function for any custom  format  specifiers
       you  write,  it takes care of truncation of length due to precision (on
       strings only) and printing initial output for numbers or strings.

       Note:

         If this function returns FALSE, you should probably just return  from
       the callback with FALSE.
     Function:  vstr_sc_fmt_cb_end()



Vstr 1.0.15                06-Mar-2006                        137





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]:  Position you added your data to the Vstr (Parameter[1]).
       Type[2]: size_t

       Parameter[3]: Format specifier passed to a callback of vstr_add_vfmt()
       Type[3]: struct Vstr_fmt_spec *

       Parameter[4]: Length of data you added.
       Type[4]: size_t

       Explanation:

         This function is a helper function for any custom  format  specifiers
       you  write, it takes care of doing the standard transforms to your data
       after it is output as if you were printing a string.

       Note:

         You shouldn't alter the position between calling vstr_sc_fmt_cb_beg()
       and  vstr_sc_fmt_cb_end(),  if padding is added in vstr_sc_fmt_cb_end()
       it is added at position (Parameter[2]) + length (Parameter[4]).
         If this function returns FALSE, you should probably just return  from
       the callback with FALSE.

     Function:  vstr_sc_fmt_add_vstr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is  used  to add a custom specifier function to print
       Vstr strings. It is equivalent to calling vstr_add_fmt() with the  type
       arguments      of     VSTR_TYPE_FMT_PTR_VOID,     VSTR_TYPE_FMT_SIZE_T,
       VSTR_TYPE_FMT_SIZE_T, VSTR_TYPE_FMT_UINT and  VSTR_TYPE_FMT_END.  These
       correspond to the last 4 arguments to vstr_add_vstr().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As you would expect the precision and field  width  values  are  used
       from  the format, so the length of the Vstr string printed is the lower
       bound of the length passed and the precision.



Vstr 1.0.15                06-Mar-2006                        138





vstr(3)                Vstr String Library                vstr(3)


         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It  is recommended that you use the name "{vstr}", with the gcc warn-
       ing    compatible    alternates    using    "{vstr:%p%zu%zu%u}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_buf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is used to add a custom specifier function to print a
       memory block. It is equivalent to calling vstr_add_fmt() with the  type
       arguments    of    VSTR_TYPE_FMT_PTR_CHAR,   VSTR_TYPE_FMT_SIZE_T   and
       VSTR_TYPE_FMT_END.  These  correspond  to  the  last  2  arguments   to
       vstr_add_buf().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As you would expect the precision and field  width  values  are  used
       from the format, so the length of the memory block printed is the lower
       bound of the length passed and the precision.
         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It is recommended that you use the name "{buf}", with the gcc warning
       compatible alternates using  "{buf:%s%zu}"  etc.  vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is used to add a custom specifier function to print a
       memory block. It is equivalent to calling vstr_add_fmt() with the  type
       arguments    of    VSTR_TYPE_FMT_PTR_CHAR,   VSTR_TYPE_FMT_SIZE_T   and
       VSTR_TYPE_FMT_END.  These  correspond  to  the  last  2  arguments   to
       vstr_add_ptr().



Vstr 1.0.15                06-Mar-2006                        139





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As you would expect the precision and field  width  values  are  used
       from the format, so the length of the memory block printed is the lower
       bound of the length passed and the precision.
         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It is recommended that you use the name "{ptr}", with the gcc warning
       compatible alternates using  "{ptr:%s%zu}"  etc.  vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_non()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is used to add a custom specifier function to print a
       memory block. It is equivalent to calling vstr_add_fmt() with the  type
       arguments  of  VSTR_TYPE_FMT_SIZE_T and VSTR_TYPE_FMT_END. These corre-
       spond to the last argument to vstr_add_non().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As  you  would  expect  the precision and field width values are used
       from the format, so the length of the memory block printed is the lower
       bound of the length passed and the precision.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{non}", with the gcc warning
       compatible alternates using "{non:%zu}" etc. vstr_sc_fmt_add_all() will
       add this formatter using those names.

     Function:  vstr_sc_fmt_add_ref()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:



Vstr 1.0.15                06-Mar-2006                        140





vstr(3)                Vstr String Library                vstr(3)


         This function is used to add a custom specifier function to  print  a
       memory  block. It is equivalent to calling vstr_add_fmt() with the type
       arguments     of     VSTR_TYPE_FMT_PTR_VOID,      VSTR_TYPE_FMT_SIZE_T,
       VSTR_TYPE_FMT_SIZE_T  and  VSTR_TYPE_FMT_END.  These  correspond to the
       last 3 arguments to vstr_add_ref().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As  you  would  expect  the precision and field width values are used
       from the format, so the length of the memory block printed is the lower
       bound of the length passed and the precision.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{ref}", with the gcc warning
       compatible alternates using "{ref:%p%zu%zu}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_rep_chr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       memory  block. It is equivalent to calling vstr_add_fmt() with the type
       arguments    of     VSTR_TYPE_FMT_INT,     VSTR_TYPE_FMT_SIZE_T     and
       VSTR_TYPE_FMT_END.   These  correspond  to  the  last  2  arguments  to
       vstr_add_rep_chr().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         As  you  would  expect  the precision and field width values are used
       from the format, so the length of the memory block printed is the lower
       bound of the length passed and the precision.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name  "{rep_chr}",  with  the  gcc
       warning    compatible    alternates    using   "{rep_chr:%c%zu}"   etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_Byte_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int




Vstr 1.0.15                06-Mar-2006                        141





vstr(3)                Vstr String Library                vstr(3)


       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "B" for bytes.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the  name  "{BKMG.u}",  with  the  gcc
       warning     compatible     alternates    using    "{BKMG.u:%u}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_Bytes_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "B/s" for bytes per second.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{BKMG/s.u}",  with  the  gcc
       warning    compatible    alternates    using    "{BKMG/s.u:%u}"    etc.



Vstr 1.0.15                06-Mar-2006                        142





vstr(3)                Vstr String Library                vstr(3)


       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_bit_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "b" for bits.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the  name  "{bKMG.u}",  with  the  gcc
       warning     compatible     alternates    using    "{bKMG.u:%u}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_bits_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "b/s" for bits per second.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.



Vstr 1.0.15                06-Mar-2006                        143





vstr(3)                Vstr String Library                vstr(3)


         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{bKMG/s.u}",  with  the  gcc
       warning    compatible    alternates    using    "{bKMG/s.u:%u}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_Byte_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "B" for bytes.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name  "{BKMG.ju}",  with  the  gcc
       warning    compatible    alternates    using    "{BKMG.ju:%ju}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_Bytes_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "B/s" for bytes per second.




Vstr 1.0.15                06-Mar-2006                        144





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{BKMG/s.u}",  with  the  gcc
       warning    compatible    alternates    using   "{BKMG/s.ju:%ju}"   etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_bit_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "b" for bits.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name  "{bKMG.ju}",  with  the  gcc
       warning    compatible    alternates    using    "{bKMG.ju:%ju}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_bkmg_bits_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *




Vstr 1.0.15                06-Mar-2006                        145





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to add a custom specifier function to  print  a
       number  in  a  human accessible form. Displaying either K, M or G after
       the number and before a "b/s" for bits per second.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision  specifies  how  many  digits  are  included after the
       "whole" part of the number, the default precision is 2.
         The padding of the number can be done with spaces or zero characters,
       and the '+' or ' ' modifiers will work as on unsigned ints.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{bKMG/s.ju}", with  the  gcc
       warning    compatible    alternates    using   "{bKMG/s.ju:%ju}"   etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv4_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom  specifier  function  to  print
       ipv4  IP addresses from a struct in_addr *. It is equivalent to calling
       vstr_add_fmt() with the type arguments  of  VSTR_TYPE_FMT_PTR_VOID  and
       VSTR_TYPE_FMT_END.  This pointer is a struct in_addr *, to be passed to
       inet_ntop().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the  name  "{ipv4.p}",  with  the  gcc
       warning     compatible     alternates    using    "{ipv4.p:%p}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv6_ptr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *



Vstr 1.0.15                06-Mar-2006                        146





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom  specifier  function  to  print
       ipv6 IP addresses from a struct in6_addr *. It is equivalent to calling
       vstr_add_fmt() with the type arguments  of  VSTR_TYPE_FMT_PTR_VOID  and
       VSTR_TYPE_FMT_END. This pointer is a struct in6_addr *, to be passed to
       inet_ntop().

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the  name  "{ipv4.p}",  with  the  gcc
       warning     compatible     alternates    using    "{ipv4.p:%p}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv4_vec()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom  specifier  function  to  print
       ipv4 IP addresses from a vector of 4 unsigned char. It is equivalent to
       calling    vstr_add_fmt()    with     the     type     arguments     of
       VSTR_TYPE_FMT_PTR_VOID   and   VSTR_TYPE_FMT_END,  the  vector  is  one
       unsigned char for each part of the ipv4 address.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the  name  "{ipv4.v}",  with  the  gcc
       warning     compatible     alternates    using    "{ipv4.v:%p}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv6_vec()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration



Vstr 1.0.15                06-Mar-2006                        147





vstr(3)                Vstr String Library                vstr(3)


       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom  specifier  function  to  print
       ipv6  IP addresses from a vector of 8 unsigned int. It is equivalent to
       calling    vstr_add_fmt()    with     the     type     arguments     of
       VSTR_TYPE_FMT_PTR_VOID,  VSTR_TYPE_FMT_UINT  and VSTR_TYPE_FMT_END, the
       vector is one unsigned int for each part of the ipv6 address, the  sec-
       ond argument of flags, change how the ipv6 address is printed.

       Note:

         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         It  is  recommended  that  you  use the name "{ipv6.v}", with the gcc
       warning    compatible    alternates    using    "{ipv6.v:%p%u}"    etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv4_vec_cidr()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is  used  to add a custom specifier function to print
       ipv4 IP addresses with a CIDR mask from a vector of 4 unsigned char and
       an  unsigned  int.  It is equivalent to calling vstr_add_fmt() with the
       type  arguments  of  VSTR_TYPE_FMT_PTR_VOID,   VSTR_TYPE_FMT_UINT   and
       VSTR_TYPE_FMT_END, the vector is one unsigned char for each part of the
       ipv4 address.

       Note:

         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         It is recommended that you use the name "{ipv4.v+C}",  with  the  gcc
       warning    compatible    alternates    using   "{ipv4.v+C:%p%u}"   etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_ipv6_vec_cidr()



Vstr 1.0.15                06-Mar-2006                        148





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom  specifier  function  to  print
       ipv6  IP addresses with a CIDR mask from a vector of 8 unsigned int and
       an unsigned int. It is equivalent to calling  vstr_add_fmt()  with  the
       type    arguments    of   VSTR_TYPE_FMT_PTR_VOID,   VSTR_TYPE_FMT_UINT,
       VSTR_TYPE_FMT_UINT and VSTR_TYPE_FMT_END, the vector  is  one  unsigned
       int  for  each  part of the ipv6 address, the second argument of flags,
       change how the ipv6 address is printed.

       Note:

         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         It is recommended that you use the name "{ipv6.v+C}",  with  the  gcc
       warning    compatible   alternates   using   "{ipv6.v+C:%p%u%u}"   etc.
       vstr_sc_fmt_add_all() will add this formatter using those names.

     Function:  vstr_sc_fmt_add_upper_base2_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to print  an
       unsigned int number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The precision, field width, #, + and - attributes  all  act  as  they
       would  on hex or octal numbers (Ie. %x or %o). The # flag prints a "0b"
       in the same way hex prints "0x".
         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It is recommended that you use the name "{B.u}", with the gcc warning



Vstr 1.0.15                06-Mar-2006                        149





vstr(3)                Vstr String Library                vstr(3)


       compatible alternates using "{B.u:%u}" etc. vstr_sc_fmt_add_all()  will
       add this formatter using those names.

     Function:  vstr_sc_fmt_add_upper_base2_ulong()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function is used to add a custom specifier function to print an
       unsigned long number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision,  field  width,  #, + and - attributes all act as they
       would on hex or octal numbers (Ie. %x or %o). The # flag prints a  "0b"
       in the same way hex prints "0x".
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{B.lu}", with the gcc  warn-
       ing compatible alternates using "{B.lu:%lu}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_upper_base2_size()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       size_t number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The precision, field width, #, + and - attributes  all  act  as  they
       would  on hex or octal numbers (Ie. %x or %o). The # flag prints a "0b"
       in the same way hex prints "0x".
         The function will return 0 if it needs to allocate memory and  cannot



Vstr 1.0.15                06-Mar-2006                        150





vstr(3)                Vstr String Library                vstr(3)


       do so.
         It  is recommended that you use the name "{B.zu}", with the gcc warn-
       ing compatible alternates using "{B.zu:%zu}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_upper_base2_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is used to add a custom specifier function to print a
       uintmax_t number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision,  field  width,  #, + and - attributes all act as they
       would on hex or octal numbers (Ie. %x or %o). The # flag prints a  "0b"
       in the same way hex prints "0x".
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{B.ju}", with the gcc  warn-
       ing compatible alternates using "{B.ju:%ju}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_lower_base2_uint()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to print  an
       unsigned int number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The precision, field width, #, + and - attributes  all  act  as  they
       would  on hex or octal numbers (Ie. %x or %o). The # flag prints a "0b"



Vstr 1.0.15                06-Mar-2006                        151





vstr(3)                Vstr String Library                vstr(3)


       in the same way hex prints "0x".
         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It is recommended that you use the name "{b.u}", with the gcc warning
       compatible alternates using "{b.u:%u}" etc. vstr_sc_fmt_add_all()  will
       add this formatter using those names.

     Function:  vstr_sc_fmt_add_lower_base2_ulong()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function is used to add a custom specifier function to print an
       unsigned long number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision,  field  width,  #, + and - attributes all act as they
       would on hex or octal numbers (Ie. %x or %o). The # flag prints a  "0b"
       in the same way hex prints "0x".
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{b.lu}", with the gcc  warn-
       ing compatible alternates using "{b.lu:%lu}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_lower_base2_size()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This function is used to add a custom specifier function to  print  a
       size_t number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.



Vstr 1.0.15                06-Mar-2006                        152





vstr(3)                Vstr String Library                vstr(3)


         The precision, field width, #, + and - attributes  all  act  as  they
       would  on hex or octal numbers (Ie. %x or %o). The # flag prints a "0b"
       in the same way hex prints "0x".
         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         It  is recommended that you use the name "{b.zu}", with the gcc warn-
       ing compatible alternates using "{b.zu:%zu}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_lower_base2_uintmax()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Specifier name, for use with vstr_add_vfmt()
       Type[2]: const char *

       Explanation:

         This  function  is used to add a custom specifier function to print a
       uintmax_t number in a base 2 form.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The  precision,  field  width,  #, + and - attributes all act as they
       would on hex or octal numbers (Ie. %x or %o). The # flag prints a  "0b"
       in the same way hex prints "0x".
         The  function will return 0 if it needs to allocate memory and cannot
       do so.
         It is recommended that you use the name "{b.ju}", with the gcc  warn-
       ing compatible alternates using "{b.ju:%ju}" etc. vstr_sc_fmt_add_all()
       will add this formatter using those names.

     Function:  vstr_sc_fmt_add_all()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Explanation:

         This function is a shortcut to adding a custom formatter for each  of
       the  specific  custom  formatters. The names used are as those given in
       the notes section of each custom formatter. Also 4 alternate names  are
       given  so  that  the  formatter can be used in a gcc warning compatible
       way. For instance the vstr_add_buf() formatter is "{buf}", however  the
       names "{buf:%s%zu}", "{buf:%*s%zu}", "{buf:%.*s%zu}", "{buf:%*.*s%zu}",
       "{buf:%d%s%zu}" and  "{buf:%d%d%s%zu}" are also added  (the  later  two
       are  slightly  less  readable,  but  required for custom formaters whos



Vstr 1.0.15                06-Mar-2006                        153





vstr(3)                Vstr String Library                vstr(3)


       first argument is a %p.

       Note:

         The function will return 0 if it needs to allocate memory and  cannot
       do so.
         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         If any of the custom formatter adds fails (for example, if  the  name
       is  already  in  use)  then all the rest of the names of that type will
       fail, however the other remaining types of formatters will be tried.

     Function:  VSTR_SC_FMT_ADD()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Function to add the custom formatter ability
       Type[2]: int (*)(struct Vstr_conf *, const char *)

       Parameter[3]: Prefix string
       Type[3]: const char *

       Parameter[4]: Static format check string, without the leading % sign
       Type[4]: const char *

       Parameter[5]: Postfix string
       Type[5]: const char *

       Explanation:

         This macro function calls the function to add the  custom  formatting
       ability  (Parameter[2]), with the Vstr configuration (Parameter[1]) and
       a string composed of the values from prefix, and the postfix.  It  then
       calls  the  function  with  the prefix, various middle strings with the
       static format check string, and the postfix.  For example the following
       call...

           VSTR_SC_FMT_ADD(NULL, func, "<foo", "p", ">");

        ...will register the format "<foo>", but also the formats "<foo:%p>",
        "<foo:%p>", "<foo:%*p>", "<foo:%.*p>", "<foo:%*.*p>", "<foo:%d%p>" and
       "<foo:%d%d%p>". This is all that is  required  to  fool  static  format
       string  checkers,  even  when  you are passing formating information in
       parameters.

       Note:

         No cleanup is done on failure, so if the  second  registration  fails
       then the first custom formatter will still be registered on return.

     Function:  vstr_sc_mmap_fd()



Vstr 1.0.15                06-Mar-2006                        154





vstr(3)                Vstr String Library                vstr(3)


       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: File descriptor
       Type[3]: int

       Parameter[4]: Offset to start map in file descriptor
       Type[4]: off64_t

       Parameter[5]: Size of map in file descriptor
       Type[5]: size_t

       Parameter[6]: Returns error code starting VSTR_TYPE_SC_MMAP_FD_ERR_
       Type[6]: unsigned int *

       Explanation:

         This  function  is  used to add a mmap()d mapping of data from a file
       descriptor (Parameter[3]) at offset (Parameter[4]) and of size (Parame-
       ter[5]) to a Vstr string.

       Note:

         If the size (Parameter[5]) is zero, then then the size of the file is
       automatically worked out and the size (Parameter[5]) becomes  the  file
       size minus the offset (Parameter[4]).

     Function:  vstr_sc_mmap_file()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Filename to add a mapping from
       Type[3]: const char *

       Parameter[4]: Offset to start map in file open()'d by filename
       Type[4]: off64_t

       Parameter[5]: Size of map in file open()'d by filename
       Type[5]: size_t

       Parameter[6]: Returns error code starting VSTR_TYPE_SC_MMAP_FILE_ERR_
       Type[6]: unsigned int *



Vstr 1.0.15                06-Mar-2006                        155





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This  function is used to add a mmap()d mapping of the entire data of
       filename (Parameter[3]) to a Vstr string.

     Function:  vstr_sc_read_iov_fd()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: File descriptor
       Type[3]: int

       Parameter[4]: Minimum amount of nodes to read into
       Type[4]: unsigned int

       Parameter[5]: Maximum amount of nodes to read into
       Type[5]: unsigned int

       Parameter[6]: Returns error code starting VSTR_TYPE_SC_READ_FD_ERR_
       Type[6]: unsigned int *

       Explanation:

         This function is used to call vstr_add_iovec_buf_beg(), then  readv()
       with     the     file    descriptor    (Parameter[3])    and    finally
       vstr_add_iovec_buf_end() before returning.

     Function:  vstr_sc_read_len_fd()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: File descriptor
       Type[3]: int

       Parameter[4]: Size of data to try to read
       Type[4]: size_t

       Parameter[5]: Returns error code starting VSTR_TYPE_SC_READ_FD_ERR_
       Type[5]: unsigned int *

       Explanation:




Vstr 1.0.15                06-Mar-2006                        156





vstr(3)                Vstr String Library                vstr(3)


         This function is used to call vstr_add_iovec_buf_beg(), then  readv()
       with     the     file    descriptor    (Parameter[3])    and    finally
       vstr_add_iovec_buf_end() before returning.
         However the arguments to the vstr_add_iovec_buf_* calls  are  limited
       so that only up to size (Parameter[4]) data will be read.
         If  size  (Parameter[4])  is zero then the entire file will try to be
       read.

       Note:

         As with all calls in the vstr library, this is a  non-blocking  call.
       If  you  need all of the data specified (Parameter[4]) then you'll need
       to loop.

     Function:  vstr_sc_read_iov_file()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Filename to read from
       Type[3]: const char *

       Parameter[4]: Offset to start reading at
       Type[4]: off64_t

       Parameter[5]: Minimum amount of nodes to read into
       Type[5]: unsigned int

       Parameter[6]: Maximum amount of nodes to read into
       Type[6]: unsigned int

       Parameter[7]: Returns error code starting VSTR_TYPE_SC_READ_FILE_ERR_
       Type[7]: unsigned int *

       Explanation:

         This function is used to call vstr_add_iovec_buf_beg(), then  readv()
       with the file descriptor got by opening the filename (Parameter[3]) and
       finally vstr_add_iovec_buf_end() before returning.
         However the arguments to the vstr_add_iovec_buf_* calls  are  limited
       so that only up to size (Parameter[4]) data will be read.
         However  the  arguments to the vstr_add_iovec_buf_* calls are limited
       so that only up to exactly size (Parameter[4]) data will  be  read.  If
       size  (Parameter[5])  is  zero  then  the entire file, minus the offset
       (Parameter[4]) will try and be read.

       Note:

         If all the data is read() and  then  close()  fails  with  an  error,



Vstr 1.0.15                06-Mar-2006                        157





vstr(3)                Vstr String Library                vstr(3)


       although the error code will signify this the data will stay inside the
       Vstr as this seemed the most useful/sane behaviour.
         read() is called multiple times from  this  function,  so  it  should
       return  after  either all the data has been read from the file into the
       Vstr or an error has occured.

     Function:  vstr_sc_read_len_file()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Filename to read from
       Type[3]: const char *

       Parameter[4]: Offset to start reading at
       Type[4]: off64_t

       Parameter[5]: Size of data to try to read
       Type[5]: size_t

       Parameter[6]: Returns error code starting VSTR_TYPE_SC_READ_FILE_ERR_
       Type[6]: unsigned int *

       Explanation:

         This function is used to call vstr_add_iovec_buf_beg(), then  readv()
       with the file descriptor got by opening the filename (Parameter[3]) and
       finally vstr_add_iovec_buf_end() before returning.
         However the arguments to the vstr_add_iovec_buf_* calls  are  limited
       so  that  only  up to exactly size (Parameter[4]) data will be read. If
       size (Parameter[5]) is zero then the  entire  file,  minus  the  offset
       (Parameter[4]) will try and be read.

       Note:

         If  all  the  data  is  read()  and then close() fails with an error,
       although the error code will signify this the data will stay inside the
       Vstr as this seemed the most useful/sane behaviour.
         read()  is  called  multiple  times  from this function, so it should
       return after either all the data has been read from the file  into  the
       Vstr or an error has occured.

     Function:  vstr_sc_write_fd()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *




Vstr 1.0.15                06-Mar-2006                        158





vstr(3)                Vstr String Library                vstr(3)


       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[3]: File descriptor
       Type[3]: int

       Parameter[4]: Returns error code starting VSTR_TYPE_SC_WRITE_FD_ERR_
       Type[4]: unsigned int *

       Explanation:

         This function is used to take data from a Vstr string and write it to
       a file descriptor. Specifically this means that after the call any data
       written  will  be  removed  from  the Vstr (Parameter[1]), making write
       analogous to read which fills in the data.

       Note:

         If the start position is 1, the  length  is  (Parameter[1])->len  and
       caching  is  available for the Vstr string the data will be exported as
       though vstr_export_iovec_ptr_all(), writev() and then  vstr_del()  were
       called.

     Function:  vstr_sc_write_file()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Filename to add a mapping from
       Type[4]: const char *

       Parameter[5]: Flags to pass to the open() system call
       Type[5]: int

       Parameter[6]: Mode to pass to the open() system call
       Type[6]: mode_t

       Parameter[7]: Offset to start writing at
       Type[7]: off64_t

       Parameter[8]: Returns error code starting VSTR_TYPE_SC_WRITE_FILE_ERR_
       Type[8]: unsigned int *




Vstr 1.0.15                06-Mar-2006                        159





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to take data from a Vstr string and write it to
       a file, after open()ing the file (Parameter[4]) with open flags (Param-
       eter[5]) and open mode (Parameter[6]).

       Note:

         Because  multiple system calls will be done inside this function, and
       that doing a write automatically removes data it's  possible  for  this
       function to return failure but have actually written some data out. The
       other alternative would be to copy all the data until after the close()
       happened, which would be vastly less efficient.

     Function:  vstr_sc_add_b_uint16()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Binary value to add
       Type[3]: uint_least16_t

       Explanation:

         This function is used to add a 16bit (two byte) binary value (Parame-
       ter[3]), in Big Endian format, to the Vstr string (Parameter[1]).

       Note:

         This function is here because too many existing network protcols send
       binary  values,  in  Big Endian format. This does not mean it is a good
       thing to do for new protcols, look at netstrings or  something  equally
       nicer.

     Function:  vstr_sc_add_b_uint32()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Append position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Binary value to add
       Type[3]: uint_least32_t

       Explanation:




Vstr 1.0.15                06-Mar-2006                        160





vstr(3)                Vstr String Library                vstr(3)


         This function is used to add a 32bit (four byte) binary value (Param-
       eter[3]), in Big Endian format, to the Vstr string (Parameter[1]).

       Note:

         This function is here because too many existing network protcols send
       binary  values,  in  Big Endian format. This does not mean it is a good
       thing to do for new protcols, look at netstrings or  something  equally
       nicer.

     Function:  vstr_sc_sub_b_uint16()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Binary value to add
       Type[4]: uint_least16_t

       Explanation:

         This  function  is used to substitute a 16bit (two byte) binary value
       (Parameter[4]), in Big Endian  format,  to  the  Vstr  string  (Parame-
       ter[1]).

       Note:

         This function is here because too many existing network protcols send
       binary values, in Big Endian format. This does not mean it  is  a  good
       thing  to  do for new protcols, look at netstrings or something equally
       nicer.

     Function:  vstr_sc_sub_b_uint32()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Binary value to add
       Type[4]: uint_least32_t



Vstr 1.0.15                06-Mar-2006                        161





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to substitute a 32bit (four byte) binary  value
       (Parameter[4]),  in  Big  Endian  format,  to  the Vstr string (Parame-
       ter[1]).

       Note:

         This function is here because too many existing network protcols send
       binary  values,  in  Big Endian format. This does not mean it is a good
       thing to do for new protcols, look at netstrings or  something  equally
       nicer.

     Function:  vstr_sc_parse_b_uint16()
       Returns: Binary value to add
       Type: uint_least16_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Explanation:

         This  function  is  used  to  parse  a  16bit (two byte) binary value
       (Parameter[4]), in Big Endian format, from  the  Vstr  string  (Parame-
       ter[1]).
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

       Note:

         This function is here because too many existing network protcols send
       binary  values,  in  Big Endian format. This does not mean it is a good
       thing to do for new protcols, look at netstrings or  something  equally
       nicer.

     Function:  vstr_sc_parse_b_uint32()
       Returns: Binary value to add
       Type: uint_least32_t

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Explanation:

         This  function  is  used  to  parse  a 32bit (four byte) binary value
       (Parameter[4]), in Big Endian format, from  the  Vstr  string  (Parame-
       ter[1]).
         If the function can detect that the values of parameters are in error



Vstr 1.0.15                06-Mar-2006                        162





vstr(3)                Vstr String Library                vstr(3)


       the function will return 0 to indicate an error.

       Note:

         This function is here because too many existing network protcols send
       binary  values,  in  Big Endian format. This does not mean it is a good
       thing to do for new protcols, look at netstrings or  something  equally
       nicer.


Interator functions
     Function:  vstr_iter_fwd_beg()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Parameter[4]: Vstr iteration
       Type[4]: struct Vstr_iter *

       Explanation:

         This function is used to initialized an iteration.

       Note:

         The  only  time  this  function  will  return FALSE is if you pass an
       invalid position and length.
         If you alter the Vstr string (Parameter[1]) while using a  iteration,
       then the iteration will be in an undefined state.

     Function:  vstr_iter_fwd_nxt()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *

       Explanation:

         This function is used to step to the next iteration.

       Note:

         If  you alter the Vstr string (Parameter[1]) while using a iteration,
       then the iteration will be in an undefined state.




Vstr 1.0.15                06-Mar-2006                        163





vstr(3)                Vstr String Library                vstr(3)


     Function:  vstr_iter_fwd_chr()
       Returns: Character at that point in iteration
       Type: char

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *

       Parameter[2]: Vstr iteration return type  (VSTR_TYPE_ITER_*).
       Type[2]: unsigned int *

       Explanation:

         This function is used to return the current character and post incre-
       ment  the  iteration  (Ie think "ret = *iter++"). However it is safe to
       call vstr_iter_fwd_chr() forever, after it gets to the end of the iter-
       ation it will just return 0 (and set the return type to _END).

       Note:

         If  you alter the Vstr string (Parameter[1]) while using a iteration,
       then the iteration will be in an undefined state.

     Function:  vstr_iter_fwd_buf()
       Returns: Length of iteration moved
       Type: size_t

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *

       Parameter[2]: Length to move iteration forward (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Data array to export to
       Type[3]: void *

       Parameter[4]: Length of data (Parameter[3])
       Type[4]: size_t

       Parameter[5]: Vstr iteration return type  (VSTR_TYPE_ITER_*).
       Type[5]: unsigned int *

       Explanation:

         This function is used to move  the  iteration  forward  a  particular
       length  (Parameter[2]). It will also export the data for the length, if
       there is room.
         It is safe to call vstr_iter_fwd_buf() forever, after it gets to  the
       end  of the iteration it will just return 0 (and set the return type to
       _END). If the passed length is greater than the length of the iteration
       left,  the  length  will  be  truncated and the truncated value will be
       returned.
         Passing NULL as the buffer (Parameter[3]) is only valid if the buffer
       length (Parameter[4]) is zero.




Vstr 1.0.15                06-Mar-2006                        164





vstr(3)                Vstr String Library                vstr(3)


       Note:

         If  you alter the Vstr string (Parameter[1]) while using a iteration,
       then the iteration will be in an undefined state.

     Function:  vstr_iter_fwd_cstr()
       Returns: Length of iteration moved
       Type: size_t

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *

       Parameter[2]: Length to move iteration forward (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Data array to export to
       Type[3]: char *

       Parameter[4]: Length of data (Parameter[3])
       Type[4]: size_t

       Parameter[5]: Vstr iteration return type  (VSTR_TYPE_ITER_*).
       Type[5]: unsigned int *

       Explanation:

         This function works like vstr_iter_fwd_buf(), except that the  buffer
       (Parameter[3])  must be non-NULL and the end of the data exported using
       the iteration will always be NIL terminated.

     Function:  vstr_iter_pos()
       Returns: Position of iteration
       Type: size_t

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         This function is used to return the current position  in  the  itera-
       tion.

     Function:  vstr_iter_len()
       Returns: Length of iteration
       Type: size_t

       Parameter[1]: Vstr iteration
       Type[1]: struct Vstr_iter *



Vstr 1.0.15                06-Mar-2006                        165





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This  function  is  used to return the length remaining of the itera-
       tion.


Miscellaneous functions
     Function:  vstr_cntl_opt()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Option type starting VSTR_CNTL_OPT_*
       Type[1]: int

       Parameter[ ... ]: Options depending on value of Parameter[1]
       Type[ ... ]: ...

       Explanation:

         This function will get or set global options.

     Function:  vstr_cntl_base()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Option type starting VSTR_CNTL_BASE_*
       Type[2]: int

       Parameter[ ... ]: Options depending on value of Parameter[2]
       Type[ ... ]: ...

       Explanation:

         This function will get or set options for the  Vstr  string  (Parame-
       ter[1]).

     Function:  vstr_cntl_conf()
       Returns: TRUE on success and FALSE on failure
       Type: int

        Parameter[1]:.br Type[1]: struct Vstr_conf *

       Parameter[2]: Option type starting VSTR_CNTL_CONF_*
       Type[2]: int

       Parameter[ ... ]: Options depending on value of Parameter[2]
       Type[ ... ]: ...

       Explanation:

         This  function  will  get  or  set options for the Vstr configuration



Vstr 1.0.15                06-Mar-2006                        166





vstr(3)                Vstr String Library                vstr(3)


       (Parameter[1]).

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  VSTR_FLAGXX()
       Returns: The value of the flags combined
       Type: unsigned int

       Parameter[1]: Name of flag type to use.
       Type[1]: <symbol>

       Parameter[ ... ]: Names of a flags in the given flag type
       Type[ ... ]: <symbol>

       Explanation:

         This  isn't  one  macro function but a group of functions that all do
       the same thing, just with different numbers of arguments. They  combine
       the  namespace requirements so that you can specify multiple flags in a
       concise manner. For instance VSTR_FLAG06() combines 6 flags. So instead
       of having to wite...

           (VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_NUL |
            VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_BEL |
            VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_BS |
            VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_HT |
            VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_LF |
            VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_VT)

        ...you can write...

           VSTR_FLAG06(CONV_UNPRINTABLE_ALLOW, NUL, BEL, BS, HT, LF, VT)

        ...which is a lot more readable as the number of flags increases.

         The  Range of macro functions is from VSTR_FLAG01() to VSTR_FLAG31(),
       the number at the end referring to how many flags are passed to it (not
       the number of parameters, which is one more than that).

     Function:  vstr_num()
       Returns: Number of nodes used in the vstr
       Type: unsigned int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])
       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t



Vstr 1.0.15                06-Mar-2006                        167





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function is used to find out how many nodes are being used for a
       given section of a vstr.
         If the function can detect that the values of parameters are in error
       the function will return 0 to indicate an error.

     Function:  vstr_cache_add()
       Returns: Cookie reference for cache function
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Name of cache function
       Type[2]: const char *

       Parameter[3]: Function to use as callback from the cache
       Type[3]:  void  *(*)(const struct Vstr_base *, size_t, size_t, unsigned
       int, void *)

       Explanation:

         This function will add the callback function  (Parameter[3])  to  the
       Vstr  configuration  for use in all Vstr strings that use the Vstr con-
       figuration and have a cache. The name of the  cache  function  (Parame-
       ter[2])  should  be  unique,  the  vstr  library  uses  names  starting
       "/vstr__/".

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The name of the cache function should be placed in permanent storage,
       Ie. only the pointer to the name will be stored so you cannot  malloc()
       the name and then free() it after calling the function.
         The  callback  function  parameters,  are  the Vstr string, position,
       length, the type of callback starting VSTR_TYPE_CACHE_ and the data for
       the cache function.
         The  callback  function  will not be called if the data for the cache
       function is NULL.
         The inline adding and delete from the Vstr strings is  not  performed
       if callbacks are registered for the string (because functions will have
       to be called anyway).

     Function:  vstr_cache_get()
       Returns: Data for cache function
       Type: void *

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Cookie reference for cache function
       Type[2]: unsigned int



Vstr 1.0.15                06-Mar-2006                        168





vstr(3)                Vstr String Library                vstr(3)


       Explanation:

         This function will get the data for the cache function.

     Function:  vstr_cache_set()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Cookie reference for cache function
       Type[2]: unsigned int

       Parameter[3]: Data for cache function
       Type[3]: void *

       Explanation:

         This function will set the data for the cache function.

       Note:

         The callback function will not be called if the data  for  the  cache
       function is NULL.

     Function:  vstr_cache_srch()
       Returns: Cookie reference for cache functions
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Name of cache function
       Type[2]: const char *

       Explanation:

         This  function  will  find  a  cache function name (Parameter[2]) and
       return the cookie reference for use in the other cache functions.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_cache_cb_sub()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Start position in the Vstr string (Parameter[1])



Vstr 1.0.15                06-Mar-2006                        169





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: size_t

       Parameter[3]: Length in the Vstr string (Parameter[1])
       Type[3]: size_t

       Explanation:

         If  you  are  substituting data in a vstr (from an iovec export, fol-
       lowed by a readv for instance or changing the data in a mmap()'d  area)
       then you can use this function to notify the vstr caching mechanisms.

       Note:

         This is a last resort function, to make the hard things possible, use
       the vstr_sub_*() functions instead.

     Function:  vstr_cache_cb_free()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: const struct Vstr_base *

       Parameter[2]: Cookie reference for cache function
       Type[2]: unsigned int

       Explanation:

         If you have generated cache data, this function will tell  the  cache
       function to free that data.

       Note:

         A  Cookie  reference of "zero" means tell all cache functions to free
       cached data. Note that this can cause severe performance degradation if
       overly used.

     Function:  vstr_data_add()
       Returns: Cookie reference for cache function
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Name of cache function
       Type[2]: const char *

       Parameter[3]: Reference to data to store in the configuration
       Type[3]: struct Vstr_ref *

       Explanation:

         This  function will add the data reference (Parameter[3]) to the Vstr
       configuration. The name of the data reference (Parameter[2]) should  be



Vstr 1.0.15                06-Mar-2006                        170





vstr(3)                Vstr String Library                vstr(3)


       unique, the vstr library will use names starting "/vstr__/".

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         The name of the cache function should be placed in permanent storage,
       Ie.  only the pointer to the name will be stored so you cannot malloc()
       the name and then free() it after calling the function (you can free it
       after calling vstr_data_del()).
         Storing  a reference that is NULL is valid, and will act like storing
       a reference to NULL.

     Function:  vstr_data_srch()
       Returns: Cookie reference for data configuration functions
       Type: unsigned int

       Parameter[1]: Vstr configuration
       Type[1]: struct Vstr_conf *

       Parameter[2]: Name of data configuration function
       Type[2]: const char *

       Explanation:

         This function will find a configuration data name (Parameter[2])  and
       return the cookie reference for use in the other data functions.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_data_del()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_conf *

       Parameter[2]: Cookie reference for configuration data function
       Type[2]: unsigned int

       Explanation:

         This function will release the reference on the  configuration  data,
       and allow the cookie to be reused on a later vstr_data_add() call.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_data_get()



Vstr 1.0.15                06-Mar-2006                        171





vstr(3)                Vstr String Library                vstr(3)


       Returns: Data for configuration data function
       Type: void *

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_conf *

       Parameter[2]: Cookie reference for configuration data function
       Type[2]: unsigned int

       Explanation:

         This function will get the data for the  configuration  data  storage
       function.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.

     Function:  vstr_data_set()
       Returns: Nothing
       Type: void

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_conf *

       Parameter[2]: Cookie reference for configuration data function
       Type[2]: unsigned int

       Parameter[3]: Reference to data to store in the configuration
       Type[3]: struct Vstr_ref *

       Explanation:

         This function will set the data for the  configuration  data  storage
       function.

       Note:

         If the configuration (Parameter[1]) is NULL, then the global configu-
       ration is used.
         Storing a reference that is NULL is valid, and will act like  storing
       a reference to NULL.
         All  allocations  are  done at vstr_data_add() time, so this function
       can never fail.

     Function:  vstr_swap_conf()
       Returns: TRUE on success and FALSE on failure
       Type: int

       Parameter[1]: Vstr string
       Type[1]: struct Vstr_base *

       Parameter[2]: New Vstr configuration; returned old Vstr configuration



Vstr 1.0.15                06-Mar-2006                        172





vstr(3)                Vstr String Library                vstr(3)


       Type[2]: struct Vstr_conf **

       Explanation:

         This function will swap a Vstr configuration into a Vstr string  pos-
       sibly  changing  the  Vstr configuration to be compatible with the Vstr
       string. On success the Vstr configuration that was being  used  by  the
       Vstr string is returned.

       Note:

         Using   this   function   allows   you   to  use  vstr_add_fmt()  and
       vstr_add_vfmt() on a Vstr that you don't own, by doing...

            if (vstr_swap_conf(notmy_vstr_string, &my_vstr_conf))
            {
              vstr_add_fmt(notmy_vstr_string, ... );
              vstr_swap_conf(notmy_vstr_string, &my_vstr_conf);
            }

        ...note that the last call swaps the configuration  back.  However  if
       you are
        not   using   any   custom   specifiers   then   you   can  just  call
       vstr_add_sysfmt() instead.
         The function will return 0 if it needs to allocate memory and  cannot
       do so.


SEE ALSO
       vstr_const(3)



























Vstr 1.0.15                06-Mar-2006                        173


