jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: form_field_validation.3,v 1.11 2023/10/17 09:52:10 nicm Exp $
2.\"
3.\"***************************************************************************
4.\" Copyright 2018-2022,2023 Thomas E. Dickey *
5.\" Copyright 1998-2010,2017 Free Software Foundation, Inc. *
6.\" *
7.\" Permission is hereby granted, free of charge, to any person obtaining a *
8.\" copy of this software and associated documentation files (the *
9.\" "Software"), to deal in the Software without restriction, including *
10.\" without limitation the rights to use, copy, modify, merge, publish, *
11.\" distribute, distribute with modifications, sublicense, and/or sell *
12.\" copies of the Software, and to permit persons to whom the Software is *
13.\" furnished to do so, subject to the following conditions: *
14.\" *
15.\" The above copyright notice and this permission notice shall be included *
16.\" in all copies or substantial portions of the Software. *
17.\" *
18.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
19.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
20.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
21.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
22.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
23.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
24.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25.\" *
26.\" Except as contained in this notice, the name(s) of the above copyright *
27.\" holders shall not be used in advertising or otherwise to promote the *
28.\" sale, use or other dealings in this Software without prior written *
29.\" authorization. *
30.\"***************************************************************************
31.\"
32.\" $Id: form_field_validation.3,v 1.11 2023/10/17 09:52:10 nicm Exp $
33.TH form_field_validation 3 2023-07-01 "ncurses 6.4" "Library calls"
34.ie \n(.g .ds `` \(lq
35.el .ds `` ``
36.ie \n(.g .ds '' \(rq
37.el .ds '' ''
38.de bP
39.ie n .IP \(bu 4
40.el .IP \(bu 2
41..
42.SH NAME
43\fBform_field_validation\fP \- data type validation for fields
44.SH SYNOPSIS
45\fB#include <form.h>\fP
46.sp
47\fBvoid *field_arg(const FIELD *\fIfield\fB);\fR
48.br
49\fBFIELDTYPE *field_type(const FIELD *\fIfield\fB);\fR
50.br
51\fBint set_field_type(FIELD *\fIfield\fB, FIELDTYPE *\fItype\fB, ...);\fR
52.sp
53/* predefined field types */
54.br
55\fBFIELDTYPE *TYPE_ALNUM;\fP
56.br
57\fBFIELDTYPE *TYPE_ALPHA;\fP
58.br
59\fBFIELDTYPE *TYPE_ENUM;\fP
60.br
61\fBFIELDTYPE *TYPE_INTEGER;\fP
62.br
63\fBFIELDTYPE *TYPE_NUMERIC;\fP
64.br
65\fBFIELDTYPE *TYPE_REGEXP;\fP
66.br
67\fBFIELDTYPE *TYPE_IPV4;\fP
68.SH DESCRIPTION
69By default, no validation is done on form fields.
70You can associate a form with with a \fIfield type\fP,
71making the form library validate input.
72.SS field_arg
73Returns a pointer to the field's argument block.
74The \fIargument block\fP is an opaque structure containing
75a copy of the arguments provided in a \fBset_field_type\fP call.
76.SS field_type
77Returns a pointer to the \fIfield type\fP associated with the form field,
78i.e., by calling \fBset_field_type\fP.
79.SS set_field_type
80The function \fBset_field_type\fP associates
81a field type with a given form field.
82This is the type checked by validation functions.
83Most field types are configurable,
84via arguments which the caller provides when calling \fBset_field_type\fP.
85.PP
86Several field types are predefined by the form library.
87.SS Predefined types
88It is possible to set up new programmer-defined field types.
89Field types are implemented via the \fBFIELDTYPE\fP data
90structure, which contains several pointers to functions.
91.PP
92See the \fBform_fieldtype\fP(3) manual page,
93which describes functions which can be used to construct
94a field-type dynamically.
95.PP
96The predefined types are as follows:
97.TP 5
98TYPE_ALNUM
99Alphanumeric data.
100Required parameter:
101.RS
102.bP
103a third \fBint\fP argument, a minimum field width.
104.RE
105.TP 5
106TYPE_ALPHA
107Character data.
108Required parameter:
109.RS
110.bP
111a third \fBint\fP argument, a minimum field width.
112.RE
113.TP 5
114TYPE_ENUM
115Accept one of a specified set of strings.
116Required parameters:
117.RS
118.bP
119a third \fB(char **)\fP argument pointing to a string list;
120.bP
121a fourth \fBint\fP flag argument to enable case-sensitivity;
122.bP
123a fifth \fBint\fP flag argument specifying whether a partial
124match must be a unique one.
125If this flag is off, a prefix matches the first
126of any set of more than one list elements with that prefix.
127.RE
128.IP
129The library copies the string list,
130so you may use a list that lives in automatic variables on the stack.
131.TP 5
132TYPE_INTEGER
133Integer data, parsable to an integer by \fBatoi\fP(3).
134Required parameters:
135.RS
136.bP
137a third \fBint\fP argument controlling the precision,
138.bP
139a fourth \fBlong\fP argument constraining minimum value,
140.bP
141a fifth \fBlong\fP constraining maximum value.
142If the maximum value is less than or equal to the minimum value, the range is
143simply ignored.
144.RE
145.IP
146On return, the field buffer is formatted according to the
147\fBprintf\fP format specification \*(``.*ld\*('',
148where the \*(``*\*('' is replaced by the precision argument.
149.IP
150For details of the precision handling see \fBprintf\fP(3).
151.TP 5
152TYPE_NUMERIC
153Numeric data (may have a decimal-point part).
154Required parameters:
155.RS
156.bP
157a third \fBint\fP argument controlling the precision,
158.bP
159a fourth \fBdouble\fP argument constraining minimum value,
160.bP
161and a fifth \fBdouble\fP constraining maximum value.
162If your system supports locales,
163the decimal point character must be the one specified by your locale.
164If the maximum value is less than or equal to the minimum value,
165the range is simply ignored.
166.RE
167.IP
168On return, the field buffer is formatted according to the
169\fBprintf\fP format specification \*(``.*f\*('',
170where the \*(``*\*('' is replaced by the precision argument.
171.IP
172For details of the precision handling see \fBprintf\fP(3).
173.TP 5
174TYPE_REGEXP
175Regular expression data.
176Required parameter:
177.RS
178.bP
179a third argument, a regular expression \fB(char *)\fP string.
180The data is valid if the regular expression matches it.
181.RE
182.IP
183Regular expressions
184are in the format of \fBregcomp\fP and \fBregexec\fP.
185.IP
186The regular expression must match the whole field.
187If you have for example, an eight character wide field,
188a regular expression "^[0\-9]*$" always
189means that you have to fill all eight positions with digits.
190If you want to allow fewer digits,
191you may use for example "^[0\-9]* *$" which is good for
192trailing spaces (up to an empty field),
193or "^ *[0\-9]* *$" which is good for
194leading and trailing spaces around the digits.
195.TP 5
196TYPE_IPV4
197An Internet Protocol Version 4 address.
198Required parameter:
199.RS
200.bP
201none
202.RE
203.IP
204The form library checks whether or not the buffer has the form \fIa.b.c.d\fP,
205where \fIa\fP, \fIb\fP, \fIc\fP, and \fId\fP are numbers in the range 0 to 255.
206Trailing blanks in the buffer are ignored.
207The address itself is not validated.
208.IP
209This is an ncurses extension;
210this field type may not be available in other curses implementations.
211.SH RETURN VALUE
212The functions \fBfield_type\fP and \fBfield_arg\fP return \fBNULL\fP on error.
213The function \fBset_field_type\fP returns one of the following:
214.TP 5
215.B E_OK
216The routine succeeded.
217.TP 5
218.B E_SYSTEM_ERROR
219System error occurred (see \fBerrno\fP(3)).
220.SH SEE ALSO
221\fBcurses\fP(3),
222\fBform\fP(3),
223\fBform_fieldtype\fP(3),
224\fBform_variables\fP(3).
225.SH NOTES
226The header file \fB<form.h>\fP automatically includes the header file
227\fB<curses.h>\fP.
228.SH PORTABILITY
229These routines emulate the System V forms library.
230They were not supported on
231Version 7 or BSD versions.
232.SH AUTHORS
233Juergen Pfeifer.
234Manual pages and adaptation for new curses by Eric S. Raymond.