hesiod/hesiod_getmailhost.3

   1 .\" $Id: hesiod_getmailhost.3,v 1.1 1996/12/08 21:38:11 ghudson Exp $
   2 .\"
   3 .\" Copyright 1996 by the Massachusetts Institute of Technology.
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this
   6 .\" software and its documentation for any purpose and without
   7 .\" fee is hereby granted, provided that the above copyright
   8 .\" notice appear in all copies and that both that copyright
   9 .\" notice and this permission notice appear in supporting
  10 .\" documentation, and that the name of M.I.T. not be used in
  11 .\" advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\" M.I.T. makes no representations about the suitability of
  14 .\" this software for any purpose.  It is provided "as is"
  15 .\" without express or implied warranty.
  16 .\"
  17 .TH HESIOD 3 "30 November 1996"
  18 .SH NAME
  19 hesiod_getmailhost, hesiod_free_postoffice \- Hesiod functions for retrieving user to postoffice mappings
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <hesiod.h>
  23 .PP
  24 .B struct hesiod_postoffice *hesiod_getmailhost(void *\fIcontext\fP,
  25 .B      const char *\fIuser\fP)
  26 .B void hesiod_free_postoffice(void *\fIcontext\fP,
  27 .B      struct hesiod_postoffice *\fIpo\fP)
  28 .PP
  29 .B cc file.c \-lhesiod
  30 .fi
  31 .SH DESCRIPTION
  32 This family of functions allows you to retrieve user to postoffice
  33 mappings using Hesiod.  To perform lookups, you need an initialized
  34 Hesiod context; see hesiod(3) for details.  Information is returned in
  35 a
  36 .I hesiod_postoffice
  37 structure, which has the following fields:
  38 .IP hesiod_po_type
  39 The type of postoffice box, typically ``POP''.
  40 .IP hesiod_po_host
  41 The hostname where the postoffice box resides.
  42 .IP hesiod_po_name
  43 The account name on the given postoffice server.
  44 .PP
  45 It is the caller's responsibility to call
  46 .I hesiod_free_postoffice
  47 with the returned postoffice entry to free the resources used by the
  48 postoffice entry.
  49 .PP
  50 Hesiod queries for postoffice information are made using the ``pobox''
  51 Hesiod type, using the username as the Hesiod name.  The corresponding
  52 entries should be space-separated lists of strings giving the type of
  53 postoffice box, the hostname, and the account name.
  54 .SH RETURN VALUES
  55 On failure,
  56 .I hesiod_getservbyname
  57 returns NULL and sets the global variable
  58 .I errno
  59 to indicate the error.
  60 .SH ERRORS
  61 .I hesiod_getmailhost
  62 may fail for any of the reasons the routine
  63 .I hesiod_resolve
  64 may fail.
  65 .SH SEE ALSO
  66 hesiod(3)