lib/libform/form_field_buffer.3

   1 .\"     $NetBSD: form_field_buffer.3,v 1.11 2004/11/24 12:26:23 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001
   4 .\"     Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au
   5 .\"
   6 .\" This code is donated to The NetBSD Foundation by the author.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd October 15, 2005
  33 .Dt FORMS 3
  34 .Os
  35 .Sh NAME
  36 .Nm field_buffer ,
  37 .Nm field_status ,
  38 .Nm set_field_buffer ,
  39 .Nm set_field_printf ,
  40 .Nm set_field_status ,
  41 .Nm set_max_field
  42 .Nd form library
  43 .Sh LIBRARY
  44 .Lb libform
  45 .Sh SYNOPSIS
  46 .In form.h
  47 .Ft char *
  48 .Fn field_buffer "FIELD *field" "int buffer"
  49 .Ft int
  50 .Fn field_status "FIELD *field"
  51 .Ft int
  52 .Fn set_field_buffer "FIELD *field" "int buffer" "char *value"
  53 .Ft int
  54 .Fn set_field_printf "FIELD *field" "int buffer" "char *fmt" "..."
  55 .Ft int
  56 .Fn set_field_status "FIELD *field" "int status"
  57 .Ft int
  58 .Fn set_max_field "FIELD *field" "int max"
  59 .Sh DESCRIPTION
  60 The
  61 .Fn field_buffer
  62 function returns the contents of the buffer number specified by
  63 .Fa buffer
  64 for the given field.
  65 If the requested buffer number exceeds the
  66 number of buffers attached to the field then
  67 .Dv NULL
  68 will be returned.
  69 If the field option
  70 .Dv O_REFORMAT
  71 is enabled on the given field then
  72 storage will be allocated to hold the reformatted buffer.
  73 This storage must be release by calling
  74 .Xr free 3
  75 when it is no longer required.
  76 If the
  77 .Dv O_REFORMAT
  78 field option is not set then no extra storage is allocated.
  79 The field buffer may be set by calling
  80 .Fn set_field_buffer
  81 which will set the given buffer number to the contents of the string
  82 passed.
  83 A buffer may also be set by calling
  84 .Fn set_field_printf
  85 which sets the buffer using the format arg
  86 .Fa fmt
  87 after being expanded using the subsequent arguments in the same manner
  88 as
  89 .Xr sprintf 3
  90 does.
  91 Calling
  92 .Fn field_status
  93 will return the status of the first buffer attached to the field.
  94 If the field has been modified then the function will return
  95 .Dv TRUE
  96 otherwise
  97 .Dv FALSE
  98 is returned, the status of the first buffer may be
  99 programmatically set by calling
 100 .Fn set_field_status .
 101 The maximum growth of a dynamic field can be set by calling
 102 .Fn set_max_field
 103 which limits the fields rows if the field is a multiline field or the
 104 fields columns if the field only has a single row.
 105 .Sh RETURN VALUES
 106 Functions returning pointers will return
 107 .Dv NULL
 108 if an error is detected.
 109 The functions that return an int will return one of the following error
 110 values:
 111 .Pp
 112 .Bl -tag -width E_UNKNOWN_COMMAND -compact
 113 .It Er E_OK
 114 The function was successful.
 115 .It Er E_BAD_ARGUMENT
 116 A bad parameter was passed to the function.
 117 .It Er E_SYSTEM_ERROR
 118 A system error occurred performing the function.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr curses 3 ,
 122 .Xr forms 3
 123 .Sh NOTES
 124 The header
 125 .Aq Pa form.h
 126 automatically includes both
 127 .Aq Pa curses.h
 128 and
 129 .Aq Pa eti.h .
 130 The function
 131 .Fn set_field_printf
 132 is a
 133 .Nx
 134 extension and must not be used in portable code.