NAME

     imadr_parse_list, imadr_get, imadr_get_property,  imadr_free
     - rfc822 address parsing routines


SYNOPSIS

     #include <rfc822.h>

     int  imadr_parse_one(char  *result,  imadr_prop_t  property,
     const char *address);

     int  imadr_parse_list(imadr_t *adr, char *line);

     int  imadr_get(imadr_t *adr, int index, char **address);

     int     imadr_get_property(imadr_t    *adr,    int    index,
     imadr_prop_t property, char **result);

     void imadr_free(imadr_t *adr);


DESCRIPTION

     imadr_parse_one() may be used  to  parse  a  single  address
     referenced  by  address  and return the desired property, in
     the caller-allocated buffer result, whose size  must  be  at
     least IMADR_PROPER_LEN bytes long.  Moreover, it can be used
     to see if an address is syntactically legal and to clean  up
     addresses  with  minor syntax problems. The former is accom-
     plished by requesting the IMADR_PROPER property.

     Upon succes the requested property is copied in this buffer,
     and  the  length of the property is returned.  See below the
     allowed values for property.

     imadr_parse_list() may be used to parse a  line  of  one  or
     more  comma-separated  RFC 822 addresses. The input line may
     be of arbitrary length. The result of the parsing is  refer-
     enced  by  the passed address context, adr, and the count of
     addresses parsed is returned.

     After calling imadr_parse_list(), each  parsed  address  may
     then  be  individually extracted from the address context by
     calling imadr_get().  The extracted address is placed in the
     buffer  referenced  by address and the length of the address
     is returned.  index argument may range from 1 to  the  count
     of  parsed  addresses  returned  by imadr_parse_list().  The
     value output by  previous  calls  to  imadr_get()  is  lost.
     Therefore,  be  sure  to  save the content of address before
     calling imadr_get() again.

     After calling  imadr_parse_list(),  each  property  of  each
     address  may  then be extracted from the address context adr
     by calling imadr_get_property().  The extracted property  is
     placed  in the buffer referenced by result and the length of
     the address is returned.  See below the allowed  values  for
     property.   index  argument may range from 1 to the count of
     parsed addresses returned by imadr_parse_list().  The  value
     output  by previous calls to imadr_get_property() related to
     a different address, is lost. Therefore, be sure to save the
     content  of  property  before  calling  imadr_get_property()
     again for a different address.

     If the following example address is parsed:
     phrase <@otherhost:user@host>

     The accepted values of property are:

     IMADR_ADDRESS     Address part ( @otherhost:user@host  )  of
                       the address

     IMADR_DOMAIN      Domain part ( host ) of the address

     IMADR_LOCAL       Local part ( user ) of the address

     IMADR_PHRASE      Phrase part ( phrase ) of the address,  if
                       any

     IMADR_PROPER      Phrase        part        (         phrase
                       <@otherhost:user@host>  )  of the address,
                       if any

     IMADR_ROUTE       Source route part ( @otherhost: )  of  the
                       address, if any

     When the address list manipulation is completed imadr_free()
     should   be   called   to   free  the  memory  allocated  by
     imadr_parse_list().  This function need  not  be  called  if
     only imadr_parse_one() has been used.


RETURN VALUES

     If  successful,  imadr_parse_list()  returns  the  count  of
     addresses   parsed.    imadr_parse_one(),  imadr_get(),  and
     imadr_get_property() return the length in byte of  the  pro-
     perty or address returned.

     -1 is returned if either the property code or index  is  out
     for range.  No address is returned.

     imadr_parse_one() also returns -1 if the  result  buffer  is
     smaller than IMADR_PROPER_LEN bytes long.


ATTRIBUTES





               _______________________________________
              |   Attribute Type   |  Attribute Value|
              |____________________|_________________|
              | Architecture       |  sparc, x86     |
              |____________________|_________________|
              | Availability       |  SUNWimsdk      |
              |____________________|_________________|
              | MT-Level           |  MT-Safe        |
              |____________________|_________________|
              | Interface Stability|  Stable         |
              |____________________|_________________|


SEE ALSO

     imta_error(3).