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