contrib/openpam/doc/man/openpam_straddch.3

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