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