lib/libutil/property.3

   1 .\"
   2 .\" Copyright (c) 1998 Jordan Hubbard
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: head/lib/libutil/property.3 236965 2012-06-12 17:02:53Z des $
  27 .\" "
  28 .Dd October 7, 1998
  29 .Dt PROPERTIES 3
  30 .Os
  31 .Sh NAME
  32 .Nm properties_read ,
  33 .Nm property_find ,
  34 .Nm properties_free
  35 .Nd "functions to allow creating simple property lists from ASCII file data"
  36 .Sh LIBRARY
  37 .Lb libutil
  38 .Sh SYNOPSIS
  39 .In libutil.h
  40 .Ft properties
  41 .Fn properties_read "int fd"
  42 .Ft char *
  43 .Fn property_find "properties list" "const char *name"
  44 .Ft void
  45 .Fn properties_free "properties list"
  46 .Sh DESCRIPTION
  47 .Bd -literal
  48 typedef struct _properties {
  49         struct _properties *next;
  50         char *name;
  51         char *value;
  52 } *properties;
  53 .Ed
  54 .Pp
  55 The function
  56 .Fn properties_read
  57 reads
  58 .Fa name = value
  59 pairs from the file descriptor passed in
  60 .Fa fd
  61 and returns the head of a new property list, assuming that the
  62 file's contents have been parsed properly, or NULL in case
  63 of error.
  64 .Pp
  65 The
  66 .Fn property_find
  67 function returns the associated value string for the property named
  68 .Fa name
  69 if found, otherwise NULL.
  70 The value returned may be up to
  71 .Dv PROPERTY_MAX_VALUE
  72 bytes in length.
  73 .Pp
  74 The
  75 .Fn properties_free
  76 function is used to free the structure returned by
  77 .Fn properties_read
  78 when it is no longer needed.
  79 .Sh FILE FORMAT
  80 Each property in the file is assumed to have the format of
  81 .Fa name = value
  82 where
  83 .Fa name
  84 is an alphanumeric string (and any punctuation not including the `=' character)
  85 and
  86 .Fa value
  87 is an arbitrary string of text terminated by a newline character.
  88 If newlines
  89 are desired, the entire value should be enclosed in { } (curly-bracket)
  90 characters.
  91 Any line beginning with a # or ; character is assumed to
  92 be a comment and will be ignored.
  93 .Sh AUTHORS
  94 .An Jordan Hubbard
  95 .Sh BUGS
  96 Simplistic.