contrib/openpam/doc/man/openpam_readline.3

   1 .\" Generated from openpam_readline.c by gendoc.pl
   2 .\" $OpenPAM: openpam_readline.c 938 2017-04-30 21:34:42Z des $
   3 .Dd April 30, 2017
   4 .Dt OPENPAM_READLINE 3
   5 .Os
   6 .Sh NAME
   7 .Nm openpam_readline
   8 .Nd read a line from a file
   9 .Sh SYNOPSIS
  10 .In sys/types.h
  11 .In stdio.h
  12 .In security/pam_appl.h
  13 .In security/openpam.h
  14 .Ft "char *"
  15 .Fn openpam_readline "FILE *f" "int *lineno" "size_t *lenp"
  16 .Sh DESCRIPTION
  17 .Bf Sy
  18 This function is deprecated and may be removed in a future release without further warning.
  19 The
  20 .Fn openpam_readlinev
  21 function may be used to achieve similar results.
  22 .Ef
  23 .Pp
  24 The
  25 .Fn openpam_readline
  26 function reads a line from a file, and returns it
  27 in a NUL-terminated buffer allocated with
  28 .Xr malloc 3 .
  29 .Pp
  30 The
  31 .Fn openpam_readline
  32 function performs a certain amount of processing
  33 on the data it reads:
  34 .Bl -bullet
  35 .It
  36 Comments (introduced by a hash sign) are stripped.
  37 .It
  38 Blank lines are ignored.
  39 .It
  40 If a line ends in a backslash, the backslash is stripped and the
  41 next line is appended.
  42 .El
  43 .Pp
  44 If
  45 .Fa lineno
  46 is not
  47 .Dv NULL ,
  48 the integer variable it points to is
  49 incremented every time a newline character is read.
  50 .Pp
  51 If
  52 .Fa lenp
  53 is not
  54 .Dv NULL ,
  55 the length of the line (not including the
  56 terminating NUL character) is stored in the variable it points to.
  57 .Pp
  58 The caller is responsible for releasing the returned buffer by passing
  59 it to
  60 .Xr free 3 .
  61 .Pp
  62 .Sh RETURN VALUES
  63 The
  64 .Fn openpam_readline
  65 function returns
  66 .Dv NULL
  67 on failure.
  68 .Sh SEE ALSO
  69 .Xr openpam_readlinev 3 ,
  70 .Xr openpam_readword 3 ,
  71 .Xr pam 3
  72 .Sh STANDARDS
  73 The
  74 .Fn openpam_readline
  75 function is an OpenPAM extension.
  76 .Sh AUTHORS
  77 The
  78 .Fn openpam_readline
  79 function and this manual page were
  80 developed for the
  81 .Fx
  82 Project by ThinkSec AS and Network Associates Laboratories, the
  83 Security Research Division of Network Associates, Inc.\& under
  84 DARPA/SPAWAR contract N66001-01-C-8035
  85 .Pq Dq CBOSS ,
  86 as part of the DARPA CHATS research program.
  87 .Pp
  88 The OpenPAM library is maintained by
  89 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .