1.\"-
2.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
3.\" Copyright (c) 2004-2011 Dag-Erling Smørgrav
4.\" All rights reserved.
5.\"
6.\" This software was developed for the FreeBSD Project by ThinkSec AS and
7.\" Network Associates Laboratories, the Security Research Division of
8.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
9.\" ("CBOSS"), as part of the DARPA CHATS research program.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\" 1. Redistributions of source code must retain the above copyright
15.\"    notice, this list of conditions and the following disclaimer.
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in the
18.\"    documentation and/or other materials provided with the distribution.
19.\" 3. The name of the author may not be used to endorse or promote
20.\"    products derived from this software without specific prior written
21.\"    permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" $Id$
36.\"
37.Dd May 26, 2012
38.Dt OPENPAM_STRADDCH 3
39.Os
40.Sh NAME
41.Nm openpam_straddch
42.Nd add a character to a string, expanding the buffer if needed
43.Sh LIBRARY
44.Lb libpam
45.Sh SYNOPSIS
46.In sys/types.h
47.In security/pam_appl.h
48.In security/openpam.h
49.Ft "int"
50.Fn openpam_straddch "char **str" "size_t *size" "size_t *len" "int ch"
51.Sh DESCRIPTION
52The
53.Fn openpam_straddch
54function appends a character to a dynamically
55allocated NUL-terminated buffer, reallocating the buffer as needed.
56.Pp
57The
58.Fa str
59argument points to a variable containing either a pointer to
60an existing buffer or
61.Dv NULL .
62If the value of the variable pointed to by
63.Fa str
64is
65.Dv NULL ,
66a new buffer
67is allocated.
68.Pp
69The
70.Fa size
71and
72.Fa len
73argument point to variables used to hold the size
74of the buffer and the length of the string it contains, respectively.
75.Pp
76If a new buffer is allocated or an existing buffer is reallocated to
77make room for the additional character,
78.Fa str
79and
80.Fa size
81are updated
82accordingly.
83.Pp
84The
85.Fn openpam_straddch
86function ensures that the buffer is always
87NUL-terminated.
88.Pp
89If the
90.Fn openpam_straddch
91function is successful, it increments the
92integer variable pointed to by
93.Fa len
94and returns 0.
95Otherwise, it leaves the variables pointed to by
96.Fa str ,
97.Fa size
98and
99.Fa len
100unmodified, sets
101.Va errno
102to
103.Dv ENOMEM
104and returns -1.
105.Pp
106.Sh RETURN VALUES
107The
108.Fn openpam_straddch
109function returns 0 on success and -1 on failure.
110.Sh SEE ALSO
111.Xr pam 3 ,
112.Xr pam_strerror 3
113.Sh STANDARDS
114The
115.Fn openpam_straddch
116function is an OpenPAM extension.
117.Sh AUTHORS
118The
119.Fn openpam_straddch
120function and this manual page were
121developed by
122.An Dag-Erling Sm\(/orgrav Aq des@des.no .
123