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