xref: /freebsd/contrib/openpam/doc/man/openpam_straddch.3 (revision ddd5b8e9b4d8957fce018c520657cdfa4ecffad3)
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 March 3, 2013
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
76The final argument,
77.Fa ch ,
78is the character that should be appended to
79the string.  If
80.Fa ch
81is 0, nothing is appended, but a new buffer is
82still allocated if
83.Fa str
84is NULL.  This can be used to
85.Do
86bootstrap
87.Dc
88the
89string.
90.Pp
91If a new buffer is allocated or an existing buffer is reallocated to
92make room for the additional character,
93.Fa str
94and
95.Fa size
96are updated
97accordingly.
98.Pp
99The
100.Fn openpam_straddch
101function ensures that the buffer is always
102NUL-terminated.
103.Pp
104If the
105.Fn openpam_straddch
106function is successful, it increments the
107integer variable pointed to by
108.Fa len
109(unless
110.Fa ch
111was 0) and returns 0.
112Otherwise, it leaves the variables pointed to by
113.Fa str ,
114.Fa size
115and
116.Fa len
117unmodified, sets
118.Va errno
119to
120.Dv ENOMEM
121and returns -1.
122.Pp
123.Sh RETURN VALUES
124The
125.Fn openpam_straddch
126function returns 0 on success and -1 on failure.
127.Sh SEE ALSO
128.Xr pam 3 ,
129.Xr pam_strerror 3
130.Sh STANDARDS
131The
132.Fn openpam_straddch
133function is an OpenPAM extension.
134.Sh AUTHORS
135The
136.Fn openpam_straddch
137function and this manual page were
138developed by
139.An Dag-Erling Sm\(/orgrav Aq des@des.no .
140