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