.\" $Id: hesiod_getmailhost.3,v 1.1 1996/12/08 21:38:11 ghudson Exp $
.\"
.\" Copyright 1996 by the Massachusetts Institute of Technology.
.\"
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright
.\" notice and this permission notice appear in supporting
.\" documentation, and that the name of M.I.T. not be used in
.\" advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.
.\" M.I.T. makes no representations about the suitability of
.\" this software for any purpose.  It is provided "as is"
.\" without express or implied warranty.
.\"
.TH HESIOD 3 "30 November 1996"
.SH NAME
hesiod_getmailhost, hesiod_free_postoffice \- Hesiod functions for retrieving user to postoffice mappings
.SH SYNOPSIS
.nf
.B #include <hesiod.h>
.PP
.B struct hesiod_postoffice *hesiod_getmailhost(void *\fIcontext\fP,
.B 	const char *\fIuser\fP)
.B void hesiod_free_postoffice(void *\fIcontext\fP,
.B 	struct hesiod_postoffice *\fIpo\fP)
.PP
.B cc file.c \-lhesiod
.fi
.SH DESCRIPTION
This family of functions allows you to retrieve user to postoffice
mappings using Hesiod.  To perform lookups, you need an initialized
Hesiod context; see hesiod(3) for details.  Information is returned in
a
.I hesiod_postoffice
structure, which has the following fields:
.IP hesiod_po_type
The type of postoffice box, typically ``POP''.
.IP hesiod_po_host
The hostname where the postoffice box resides.
.IP hesiod_po_name
The account name on the given postoffice server.
.PP
It is the caller's responsibility to call
.I hesiod_free_postoffice
with the returned postoffice entry to free the resources used by the
postoffice entry.
.PP
Hesiod queries for postoffice information are made using the ``pobox''
Hesiod type, using the username as the Hesiod name.  The corresponding
entries should be space-separated lists of strings giving the type of
postoffice box, the hostname, and the account name.
.SH RETURN VALUES
On failure,
.I hesiod_getservbyname
returns NULL and sets the global variable
.I errno
to indicate the error.
.SH ERRORS
.I hesiod_getmailhost
may fail for any of the reasons the routine
.I hesiod_resolve
may fail.
.SH SEE ALSO
hesiod(3)