1.\" Generated from openpam_readword.c by gendoc.pl
2.\" $OpenPAM: openpam_readword.c 938 2017-04-30 21:34:42Z des $
3.Dd February 24, 2019
4.Dt OPENPAM_READWORD 3
5.Os
6.Sh NAME
7.Nm openpam_readword
8.Nd read a word from a file, respecting shell quoting rules
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_readword "FILE *f" "int *lineno" "size_t *lenp"
16.Sh DESCRIPTION
17The
18.Fn openpam_readword
19function reads the next word from a file, and
20returns it in a NUL-terminated buffer allocated with
21.Xr malloc 3 .
22.Pp
23A word is a sequence of non-whitespace characters.
24However, whitespace characters can be included in a word if quoted or
25escaped according to the following rules:
26.Bl -bullet
27.It
28An unescaped single or double quote introduces a quoted string,
29which ends when the same quote character is encountered a second
30time.
31The quotes themselves are stripped.
32.It
33Within a single- or double-quoted string, all whitespace characters,
34including the newline character, are preserved as-is.
35.It
36Outside a quoted string, a backslash escapes the next character,
37which is preserved as-is, unless that character is a newline, in
38which case it is discarded and reading continues at the beginning of
39the next line as if the backslash and newline had not been there.
40In all cases, the backslash itself is discarded.
41.It
42Within a single-quoted string, double quotes and backslashes are
43preserved as-is.
44.It
45Within a double-quoted string, a single quote is preserved as-is,
46and a backslash is preserved as-is unless used to escape a double
47quote.
48.El
49.Pp
50In addition, if the first non-whitespace character on the line is a
51hash character (#), the rest of the line is discarded.
52If a hash character occurs within a word, however, it is preserved
53as-is.
54A backslash at the end of a comment does cause line continuation.
55.Pp
56If
57.Fa lineno
58is not
59.Dv NULL ,
60the integer variable it points to is
61incremented every time a quoted or escaped newline character is read.
62.Pp
63If
64.Fa lenp
65is not
66.Dv NULL ,
67the length of the word (after quotes and
68backslashes have been removed) is stored in the variable it points to.
69.Sh RETURN VALUES
70If successful, the
71.Fn openpam_readword
72function returns a pointer to a
73dynamically allocated NUL-terminated string containing the first word
74encountered on the line.
75.Pp
76The caller is responsible for releasing the returned buffer by passing
77it to
78.Xr free 3 .
79.Pp
80If
81.Fn openpam_readword
82reaches the end of the line or file before any
83characters are copied to the word, it returns
84.Dv NULL .
85In the former
86case, the newline is pushed back to the file.
87.Pp
88If
89.Fn openpam_readword
90reaches the end of the file while a quote or
91backslash escape is in effect, it sets
92.Va errno
93to
94.Dv EINVAL
95and returns
96.Dv NULL .
97.Sh IMPLEMENTATION NOTES
98The parsing rules are intended to be equivalent to the normal POSIX
99shell quoting rules.
100Any discrepancy is a bug and should be reported to the author along
101with sample input that can be used to reproduce the error.
102.Pp
103.Sh SEE ALSO
104.Xr openpam_readline 3 ,
105.Xr openpam_readlinev 3 ,
106.Xr pam 3
107.Sh STANDARDS
108The
109.Fn openpam_readword
110function is an OpenPAM extension.
111.Sh AUTHORS
112The
113.Fn openpam_readword
114function and this manual page were
115developed by
116.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
117