1.\" Generated from openpam_straddch.c by gendoc.pl
2.\" $OpenPAM: openpam_straddch.c 938 2017-04-30 21:34:42Z des $
3.Dd February 24, 2019
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