152 lines
4.1 KiB
Groff
152 lines
4.1 KiB
Groff
.\" $NetBSD: hesiod.3,v 1.5 2002/02/07 07:00:21 ross Exp $
|
|
.\"
|
|
.\" from: #Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp #
|
|
.\"
|
|
.\" Copyright 1988, 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.
|
|
.\"
|
|
.Dd September 16, 2001
|
|
.Dt HESIOD 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm hesiod ,
|
|
.Nm hesiod_init ,
|
|
.Nm hesiod_resolve ,
|
|
.Nm hesiod_free_list ,
|
|
.Nm hesiod_to_bind ,
|
|
.Nm hesiod_end
|
|
.Nd Hesiod name server interface library
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]hesiod.h\*[Gt]
|
|
.Ft int
|
|
.Fn hesiod_init "void **context"
|
|
.Ft char
|
|
.Fn **hesiod_resolve "void *context" "const char *name" "const char *type"
|
|
.Ft void
|
|
.Fn hesiod_free_list "void *context" "char **list"
|
|
.Ft char
|
|
.Fn *hesiod_to_bind "void *context" "const char *name" "const char *type"
|
|
.Ft void
|
|
.Fn hesiod_end "void *context"
|
|
.Sh DESCRIPTION
|
|
This family of functions allows you to perform lookups of Hesiod
|
|
information, which is stored as text records in the Domain Name
|
|
Service. To perform lookups, you must first initialize a
|
|
.Fa context ,
|
|
an opaque object which stores information used internally by the
|
|
library between calls.
|
|
.Fn hesiod_init
|
|
initializes a context, storing a pointer to the context in the
|
|
location pointed to by the
|
|
.Fa context
|
|
argument.
|
|
.Fn hesiod_end
|
|
frees the resources used by a context.
|
|
.Pp
|
|
.Fn hesiod_resolve
|
|
is the primary interface to the library. If successful, it returns a
|
|
list of one or more strings giving the records matching
|
|
.Fa name
|
|
and
|
|
.Fa type .
|
|
The last element of the list is followed by a
|
|
.Dv NULL
|
|
pointer. It is the caller's responsibility to call
|
|
.Fn hesiod_free_list
|
|
to free the resources used by the returned list.
|
|
.Pp
|
|
.Fn hesiod_to_bind
|
|
converts
|
|
.Fa name
|
|
and
|
|
.Fa type
|
|
into the DNS name used by
|
|
.Fn hesiod_resolve .
|
|
It is the caller's responsibility to free the returned string using
|
|
.Xr free 3 .
|
|
.Sh RETURN VALUES
|
|
If successful,
|
|
.Fn hesiod_init
|
|
returns 0; otherwise it returns \-1 and sets
|
|
.Va errno
|
|
to indicate the error. On failure,
|
|
.Fn hesiod_resolve
|
|
and
|
|
.Fn hesiod_to_bind
|
|
return
|
|
.Dv NULL
|
|
and set the global variable
|
|
.Va errno
|
|
to indicate the error.
|
|
.Sh ENVIRONMENT
|
|
If the environment variable
|
|
.Ev HES_DOMAIN
|
|
is set, it will override the domain in the Hesiod configuration file.
|
|
If the environment variable
|
|
.Ev HESIOD_CONFIG
|
|
is set, it specifies the location of the Hesiod configuration file.
|
|
.Sh ERRORS
|
|
Hesiod calls may fail because of:
|
|
.Bl -tag -width ECONNREFUSED -compact
|
|
.It Er ENOMEM
|
|
Insufficient memory was available to carry out the requested operation.
|
|
.It Er ENOEXEC
|
|
.Fn hesiod_init
|
|
failed because the Hesiod configuration file was invalid.
|
|
.It Er ECONNREFUSED
|
|
.Fn hesiod_resolve
|
|
failed because no name server could be contacted to answer the query.
|
|
.It Er EMSGSIZE
|
|
.Fn hesiod_resolve
|
|
or
|
|
.Fn hesiod_to_bind
|
|
failed because the query or response was too big to fit into the
|
|
packet buffers.
|
|
.It Er ENOENT
|
|
.Fn hesiod_resolve
|
|
failed because the name server had no text records matching
|
|
.Fa name
|
|
and
|
|
.Fa type ,
|
|
or
|
|
.Fn hesiod_to_bind
|
|
failed because the
|
|
.Fa name
|
|
argument had a domain extension which could not be resolved with type
|
|
.Dq rhs-extension
|
|
in the local Hesiod domain.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr hesiod.conf 5 ,
|
|
.Xr named 8
|
|
.Rs
|
|
.%T Hesiod - Project Athena Technical Plan -- Name Service
|
|
.Re
|
|
.Sh AUTHORS
|
|
Steve Dyer, IBM/Project Athena
|
|
.br
|
|
Greg Hudson, MIT Team Athena
|
|
.br
|
|
Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology.
|
|
.Sh BUGS
|
|
The strings corresponding to the
|
|
.Ev errno
|
|
values set by the Hesiod functions are not particularly indicative of
|
|
what went wrong, especially for
|
|
.Er ENOEXEC
|
|
and
|
|
.Er ENOENT .
|