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