contrib/openpam/doc/man/openpam_straddch.3

   1 .\" Generated from openpam_straddch.c by gendoc.pl
   2 .\" $OpenPAM: openpam_straddch.c 938 2017-04-30 21:34:42Z des $
   3 .Dd February 24, 2019
   4 .Dt OPENPAM_STRADDCH 3
   5 .Os
   6 .Sh NAME
   7 .Nm openpam_straddch
   8 .Nd add a character to a string, expanding the buffer if needed
   9 .Sh SYNOPSIS
  10 .In sys/types.h
  11 .In security/pam_appl.h
  12 .In security/openpam.h
  13 .Ft "int"
  14 .Fn openpam_straddch "char **str" "size_t *size" "size_t *len" "int ch"
  15 .Sh DESCRIPTION
  16 The
  17 .Fn openpam_straddch
  18 function appends a character to a dynamically
  19 allocated NUL-terminated buffer, reallocating the buffer as needed.
  20 .Pp
  21 The
  22 .Fa str
  23 argument points to a variable containing either a pointer to
  24 an existing buffer or
  25 .Dv NULL .
  26 If the value of the variable pointed to by
  27 .Fa str
  28 is
  29 .Dv NULL ,
  30 a new buffer
  31 is allocated.
  32 .Pp
  33 The
  34 .Fa size
  35 and
  36 .Fa len
  37 argument point to variables used to hold the size
  38 of the buffer and the length of the string it contains, respectively.
  39 .Pp
  40 The final argument,
  41 .Fa ch ,
  42 is the character that should be appended to
  43 the string.  If
  44 .Fa ch
  45 is 0, nothing is appended, but a new buffer is
  46 still allocated if
  47 .Fa str
  48 is NULL.  This can be used to
  49 .Do
  50 bootstrap
  51 .Dc
  52 the
  53 string.
  54 .Pp
  55 If a new buffer is allocated or an existing buffer is reallocated to
  56 make room for the additional character,
  57 .Fa str
  58 and
  59 .Fa size
  60 are updated
  61 accordingly.
  62 .Pp
  63 The
  64 .Fn openpam_straddch
  65 function ensures that the buffer is always
  66 NUL-terminated.
  67 .Pp
  68 If the
  69 .Fn openpam_straddch
  70 function is successful, it increments the
  71 integer variable pointed to by
  72 .Fa len
  73 (unless
  74 .Fa ch
  75 was 0) and returns 0.
  76 Otherwise, it leaves the variables pointed to by
  77 .Fa str ,
  78 .Fa size
  79 and
  80 .Fa len
  81 unmodified, sets
  82 .Va errno
  83 to
  84 .Dv ENOMEM
  85 and returns -1.
  86 .Pp
  87 .Sh RETURN VALUES
  88 The
  89 .Fn openpam_straddch
  90 function returns 0 on success and -1 on failure.
  91 .Sh SEE ALSO
  92 .Xr pam 3 ,
  93 .Xr pam_strerror 3
  94 .Sh STANDARDS
  95 The
  96 .Fn openpam_straddch
  97 function is an OpenPAM extension.
  98 .Sh AUTHORS
  99 The
 100 .Fn openpam_straddch
 101 function and this manual page were
 102 developed by
 103 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .