libs/src/str/strprint.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: strprint.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH STRPRINT 3X "30 September 1992"
   7 .SH NAME
   8 str_sprint, tr_sprintv, str_nprint, str_nprintv, str_print, str_printv, strx_sprint, strx_sprintv, strx_nprint, strx_nprintv, strx_print, strx_printv -- formatted conversion to string
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "str.h"
  14 .LP
  15 .ft B
  16 char *str_sprint( buf, format, ... )
  17 char *buf ;
  18 char *format ;
  19 .LP
  20 .ft B
  21 char *str_sprintv( buf, format, ap )
  22 char *buf ;
  23 char *format ;
  24 va_list ap ;
  25 .LP
  26 .ft B
  27 int str_nprint( buf, format, ... )
  28 char *buf ;
  29 char *format ;
  30 .LP
  31 .ft B
  32 int str_nprintv( buf, format, ap )
  33 char *buf ;
  34 char *format ;
  35 va_list ap ;
  36 .LP
  37 .ft B
  38 void str_print( countp, buf, format, ... )
  39 int *countp ;
  40 char *buf ;
  41 char *format ;
  42 .LP
  43 .ft B
  44 void str_printv( countp, buf, format, ap )
  45 int *countp ;
  46 char *buf ;
  47 char *format ;
  48 va_list ap ;
  49 .LP
  50 .ft B
  51 char *strx_sprint( buf, len, format, ... )
  52 char *buf ;
  53 int len ;
  54 char *format ;
  55 .LP
  56 .ft B
  57 char *strx_sprintv( buf, len, format, ap )
  58 char *buf ;
  59 int len ;
  60 char *format ;
  61 va_list ap ;
  62 .LP
  63 .ft B
  64 int strx_nprint( buf, len, format, ... )
  65 char *buf ;
  66 int len ;
  67 char *format ;
  68 .LP
  69 .ft B
  70 int strx_nprintv( buf, len, format, ap )
  71 char *buf ;
  72 int len ;
  73 char *format ;
  74 va_list ap ;
  75 .LP
  76 .ft B
  77 void strx_print( countp, buf, len, format, ... )
  78 int *countp ;
  79 char *buf ;
  80 int len ;
  81 char *format ;
  82 .LP
  83 .ft B
  84 void strx_printv( countp, buf, len, format, ap )
  85 int *countp ;
  86 char *buf ;
  87 int len ;
  88 char *format ;
  89 va_list ap ;
  90 .SH DESCRIPTION
  91 .LP
  92 All functions are similar in functionality to \fIsprintf()\fR.
  93 Their only difference is in their return values. For information about their
  94 conversion capabilities, check \fISprint(3)\fR.
  95 .LP
  96 The difference between the \fIstr_*\fR and the \fIstrx_*\fR functions
  97 is that the latter take an extra argument, the size of the buffer, so
  98 that they will never write beyond the end of the buffer. Writing
  99 beyond the end of the buffer is possible with the \fIstr_*\fR functions.
 100 Previously, invoking any of the \fIstrx_*\fR functions with the
 101 .I len
 102 argument set to 0
 103 used to be the same as calling the equivalent \fIstr_*\fR function.
 104 This dangerous behavior has since been changed and now the \fIstrx_*\fR
 105 functions don't touch the buffer when
 106 .I len
 107 is 0 or negative.
 108 .LP
 109 All functions will append a
 110 .SM NUL
 111 at the end of
 112 .I buf
 113 (the \fIstrx_*\fR functions will not do this if it would cause
 114 a buffer overrun).
 115 .LP
 116 .B str_print(),
 117 .B str_printv(),
 118 .B strx_print(),
 119 and
 120 .B strx_printv()
 121 will put in
 122 .I "*countp"
 123 the number of characters placed in
 124 .I buf
 125 excluding the ending
 126 .SM NUL
 127 (this happens only if
 128 .I "*countp"
 129 is not
 130 .SM NULL
 131 ).
 132 .LP
 133 The functions that have a name ending in 'v' are similar to those without
 134 the 'v' at the end of their name
 135 except that instead of accepting a variable number of arguments, they
 136 expect a \fIstdarg(3)\fR argument list.
 137 .SH "RETURN VALUES"
 138 .LP
 139 .B str_sprint(),
 140 .B str_sprintv(),
 141 .B strx_sprint(),
 142 and
 143 .B strx_sprintv()
 144 return
 145 .I buf.
 146 .LP
 147 .B str_nprint(),
 148 .B str_nprintv(),
 149 .B strx_nprint(),
 150 and
 151 .B strx_nprintv()
 152 return the number of characters placed in
 153 .I buf
 154 excluding the ending
 155 .SM NUL.
 156 .SH "SEE ALSO"
 157 Sprint(3)