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