contrib/openpam/doc/man/openpam_straddch.3

   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
  52 The
  53 .Fn openpam_straddch
  54 function appends a character to a dynamically
  55 allocated NUL-terminated buffer, reallocating the buffer as needed.
  56 .Pp
  57 The
  58 .Fa str
  59 argument points to a variable containing either a pointer to
  60 an existing buffer or
  61 .Dv NULL .
  62 If the value of the variable pointed to by
  63 .Fa str
  64 is
  65 .Dv NULL ,
  66 a new buffer
  67 is allocated.
  68 .Pp
  69 The
  70 .Fa size
  71 and
  72 .Fa len
  73 argument point to variables used to hold the size
  74 of the buffer and the length of the string it contains, respectively.
  75 .Pp
  76 The final argument,
  77 .Fa ch ,
  78 is the character that should be appended to
  79 the string.  If
  80 .Fa ch
  81 is 0, nothing is appended, but a new buffer is
  82 still allocated if
  83 .Fa str
  84 is NULL.  This can be used to
  85 .Do
  86 bootstrap
  87 .Dc
  88 the
  89 string.
  90 .Pp
  91 If a new buffer is allocated or an existing buffer is reallocated to
  92 make room for the additional character,
  93 .Fa str
  94 and
  95 .Fa size
  96 are updated
  97 accordingly.
  98 .Pp
  99 The
 100 .Fn openpam_straddch
 101 function ensures that the buffer is always
 102 NUL-terminated.
 103 .Pp
 104 If the
 105 .Fn openpam_straddch
 106 function is successful, it increments the
 107 integer variable pointed to by
 108 .Fa len
 109 (unless
 110 .Fa ch
 111 was 0) and returns 0.
 112 Otherwise, it leaves the variables pointed to by
 113 .Fa str ,
 114 .Fa size
 115 and
 116 .Fa len
 117 unmodified, sets
 118 .Va errno
 119 to
 120 .Dv ENOMEM
 121 and returns -1.
 122 .Pp
 123 .Sh RETURN VALUES
 124 The
 125 .Fn openpam_straddch
 126 function returns 0 on success and -1 on failure.
 127 .Sh SEE ALSO
 128 .Xr pam 3 ,
 129 .Xr pam_strerror 3
 130 .Sh STANDARDS
 131 The
 132 .Fn openpam_straddch
 133 function is an OpenPAM extension.
 134 .Sh AUTHORS
 135 The
 136 .Fn openpam_straddch
 137 function and this manual page were
 138 developed by
 139 .An Dag-Erling Sm\(/orgrav Aq des@des.no .