xref: /freebsd/lib/libc/net/hesiod.3 (revision ae83180158c4c937f170e31eff311b18c0286a93)
1.\"	$NetBSD: hesiod.3,v 1.1 1999/01/25 03:43:04 lukem Exp $
2.\"	$FreeBSD$
3.\"
4.\" from: #Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp #
5.\"
6.\" Copyright 1988, 1996 by the Massachusetts Institute of Technology.
7.\"
8.\" Permission to use, copy, modify, and distribute this
9.\" software and its documentation for any purpose and without
10.\" fee is hereby granted, provided that the above copyright
11.\" notice appear in all copies and that both that copyright
12.\" notice and this permission notice appear in supporting
13.\" documentation, and that the name of M.I.T. not be used in
14.\" advertising or publicity pertaining to distribution of the
15.\" software without specific, written prior permission.
16.\" M.I.T. makes no representations about the suitability of
17.\" this software for any purpose.  It is provided "as is"
18.\" without express or implied warranty.
19.\"
20.Dd November 30, 1996
21.Dt HESIOD 3
22.Os
23.Sh NAME
24.Nm hesiod ,
25.Nm hesiod_init ,
26.Nm hesiod_resolve ,
27.Nm hesiod_free_list ,
28.Nm hesiod_to_bind ,
29.Nm hesiod_end
30.Nd Hesiod name server interface library
31.Sh LIBRARY
32.Lb libc
33.Sh SYNOPSIS
34.In hesiod.h
35.Ft int
36.Fn hesiod_init "void **context"
37.Ft char **
38.Fn hesiod_resolve "void *context" "const char *name" "const char *type"
39.Ft void
40.Fn hesiod_free_list "void *context" "char **list"
41.Ft char *
42.Fn hesiod_to_bind "void *context" "const char *name" "const char *type"
43.Ft void
44.Fn hesiod_end "void *context"
45.Sh DESCRIPTION
46This family of functions allows you to perform lookups of Hesiod
47information, which is stored as text records in the Domain Name
48Service.
49To perform lookups, you must first initialize a
50.Fa context ,
51an opaque object which stores information used internally by the
52library between calls.
53.Fn hesiod_init
54initializes a context, storing a pointer to the context in the
55location pointed to by the
56.Fa context
57argument.
58.Fn hesiod_end
59frees the resources used by a context.
60.Pp
61.Fn hesiod_resolve
62is the primary interface to the library.
63If successful, it returns a
64list of one or more strings giving the records matching
65.Fa name
66and
67.Fa type .
68The last element of the list is followed by a
69.Dv NULL
70pointer.
71It is the
72caller's responsibility to call
73.Fn hesiod_free_list
74to free the resources used by the returned list.
75.Pp
76.Fn hesiod_to_bind
77converts
78.Fa name
79and
80.Fa type
81into the DNS name used by
82.Fn hesiod_resolve .
83It is the caller's responsibility to free the returned string using
84.Fn free .
85.Sh RETURN VALUES
86.Rv -std hesiod_init
87On failure,
88.Fn hesiod_resolve
89and
90.Fn hesiod_to_bind
91return
92.Dv NULL
93and set the global variable
94.Va errno
95to indicate the error.
96.Sh ENVIRONMENT
97.Bl -tag -width HESIOD_CONFIG
98.It Ev HES_DOMAIN
99If the environment variable
100.Ev HES_DOMAIN
101is set, it will override the domain in the Hesiod configuration file.
102.It Ev HESIOD_CONFIG
103If the environment variable
104.Ev HESIOD_CONFIG
105is set, it specifies the location of the Hesiod configuration file.
106.El
107.Sh SEE ALSO
108.Xr hesiod.conf 5 ,
109.Xr named 8
110.Rs
111.%T "Hesiod - Project Athena Technical Plan -- Name Service"
112.Re
113.Sh ERRORS
114Hesiod calls may fail because of:
115.Bl -tag -width Er
116.It Bq Er ENOMEM
117Insufficient memory was available to carry out the requested
118operation.
119.It Bq Er ENOEXEC
120.Fn hesiod_init
121failed because the Hesiod configuration file was invalid.
122.It Bq Er ECONNREFUSED
123.Fn hesiod_resolve
124failed because no name server could be contacted to answer the query.
125.It Bq Er EMSGSIZE
126.Fn hesiod_resolve
127or
128.Fn hesiod_to_bind
129failed because the query or response was too big to fit into the
130packet buffers.
131.It Bq Er ENOENT
132.Fn hesiod_resolve
133failed because the name server had no text records matching
134.Fa name
135and
136.Fa type ,
137or
138.Fn hesiod_to_bind
139failed because the
140.Fa name
141argument had a domain extension which could not be resolved with type
142.Dq rhs\-extension
143in the local Hesiod domain.
144.El
145.Sh AUTHORS
146.An Steve Dyer ,
147IBM/Project Athena
148.An Greg Hudson ,
149MIT Team Athena
150.Pp
151Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology.
152.Sh BUGS
153The strings corresponding to the
154.Va errno
155values set by the Hesiod functions are not particularly indicative of
156what went wrong, especially for
157.Er ENOEXEC
158and
159.Er ENOENT .
160