2 * Copyright (C) 2004, 2006 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: name.h,v 1.95.2.3.2.14 2006/03/02 00:37:20 marka Exp $ */
28 * DNS Names and Labels
30 * Provides facilities for manipulating DNS names and labels, including
31 * conversions to and from wire format and text format.
33 * Given the large number of names possible in a nameserver, and because
34 * names occur in rdata, it was important to come up with a very efficient
35 * way of storing name data, but at the same time allow names to be
36 * manipulated. The decision was to store names in uncompressed wire format,
37 * and not to make them fully abstracted objects; i.e. certain parts of the
38 * server know names are stored that way. This saves a lot of memory, and
39 * makes adding names to messages easy. Having much of the server know
40 * the representation would be perilous, and we certainly don't want each
41 * user of names to be manipulating such a low-level structure. This is
42 * where the Names and Labels module comes in. The module allows name or
43 * label handles to be created and attached to uncompressed wire format
44 * regions. All name operations and conversions are done through these
48 * Clients of this module must impose any required synchronization.
51 * This module deals with low-level byte streams. Errors in any of
52 * the functions are likely to crash the server or corrupt memory.
61 * dns_name_fromwire() deals with raw network data. An error in
62 * this routine could result in the failure or hijacking of the server.
67 * Draft Binary Labels (2)
77 #include <isc/boolean.h>
79 #include <isc/magic.h>
80 #include <isc/region.h> /* Required for storage size of dns_label_t. */
82 #include <dns/types.h>
89 ***** A 'label' is basically a region. It contains one DNS wire format
90 ***** label of type 00 (ordinary).
96 ***** A 'name' is a handle to a binary region. It contains a sequence of one
97 ***** or more DNS wire format labels of type 00 (ordinary).
98 ***** Note that all names are not required to end with the root label,
99 ***** as they are in the actual DNS wire protocol.
103 *** Compression pointer chaining limit
106 #define DNS_POINTER_MAXHOPS 16
113 * Clients are strongly discouraged from using this type directly, with
114 * the exception of the 'link' and 'list' fields which may be used directly
115 * for whatever purpose the client desires.
119 unsigned char * ndata;
122 unsigned int attributes;
123 unsigned char * offsets;
124 isc_buffer_t * buffer;
125 ISC_LINK(dns_name_t) link;
126 ISC_LIST(dns_rdataset_t) list;
129 #define DNS_NAME_MAGIC ISC_MAGIC('D','N','S','n')
131 #define DNS_NAMEATTR_ABSOLUTE 0x0001
132 #define DNS_NAMEATTR_READONLY 0x0002
133 #define DNS_NAMEATTR_DYNAMIC 0x0004
134 #define DNS_NAMEATTR_DYNOFFSETS 0x0008
136 * Attributes below 0x0100 reserved for name.c usage.
138 #define DNS_NAMEATTR_CACHE 0x0100 /* Used by resolver. */
139 #define DNS_NAMEATTR_ANSWER 0x0200 /* Used by resolver. */
140 #define DNS_NAMEATTR_NCACHE 0x0400 /* Used by resolver. */
141 #define DNS_NAMEATTR_CHAINING 0x0800 /* Used by resolver. */
142 #define DNS_NAMEATTR_CHASE 0x1000 /* Used by resolver. */
143 #define DNS_NAMEATTR_WILDCARD 0x2000 /* Used by server. */
145 #define DNS_NAME_DOWNCASE 0x0001
146 #define DNS_NAME_CHECKNAMES 0x0002 /* Used by rdata. */
147 #define DNS_NAME_CHECKNAMESFAIL 0x0004 /* Used by rdata. */
148 #define DNS_NAME_CHECKREVERSE 0x0008 /* Used by rdata. */
150 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname;
151 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname;
154 * Standard size of a wire format name
156 #define DNS_NAME_MAXWIRE 255
163 dns_name_init(dns_name_t *name, unsigned char *offsets);
168 * 'offsets' is never required to be non-NULL, but specifying a
169 * dns_offsets_t for 'offsets' will improve the performance of most
170 * name operations if the name is used more than once.
173 * 'name' is not NULL and points to a struct dns_name.
175 * offsets == NULL or offsets is a dns_offsets_t.
178 * 'name' is a valid name.
179 * dns_name_countlabels(name) == 0
180 * dns_name_isabsolute(name) == ISC_FALSE
184 dns_name_reset(dns_name_t *name);
186 * Reinitialize 'name'.
189 * This function distinguishes itself from dns_name_init() in two
192 * + If any buffer is associated with 'name' (via dns_name_setbuffer()
193 * or by being part of a dns_fixedname_t) the link to the buffer
194 * is retained but the buffer itself is cleared.
196 * + Of the attributes associated with 'name', all are retained except
197 * DNS_NAMEATTR_ABSOLUTE.
200 * 'name' is a valid name.
203 * 'name' is a valid name.
204 * dns_name_countlabels(name) == 0
205 * dns_name_isabsolute(name) == ISC_FALSE
209 dns_name_invalidate(dns_name_t *name);
211 * Make 'name' invalid.
214 * 'name' is a valid name.
217 * If assertion checking is enabled, future attempts to use 'name'
218 * without initializing it will cause an assertion failure.
220 * If the name had a dedicated buffer, that association is ended.
225 *** Dedicated Buffers
229 dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer);
231 * Dedicate a buffer for use with 'name'.
234 * Specification of a target buffer in dns_name_fromwire(),
235 * dns_name_fromtext(), and dns_name_concatentate() is optional if
236 * 'name' has a dedicated buffer.
238 * The caller must not write to buffer until the name has been
239 * invalidated or is otherwise known not to be in use.
241 * If buffer is NULL and the name previously had a dedicated buffer,
242 * than that buffer is no longer dedicated to use with this name.
243 * The caller is responsible for ensuring that the storage used by
244 * the name remains valid.
247 * 'name' is a valid name.
249 * 'buffer' is a valid binary buffer and 'name' doesn't have a
250 * dedicated buffer already, or 'buffer' is NULL.
254 dns_name_hasbuffer(const dns_name_t *name);
256 * Does 'name' have a dedicated buffer?
259 * 'name' is a valid name.
262 * ISC_TRUE 'name' has a dedicated buffer.
263 * ISC_FALSE 'name' does not have a dedicated buffer.
272 dns_name_isabsolute(const dns_name_t *name);
274 * Does 'name' end in the root label?
277 * 'name' is a valid name
280 * TRUE The last label in 'name' is the root label.
281 * FALSE The last label in 'name' is not the root label.
285 dns_name_iswildcard(const dns_name_t *name);
287 * Is 'name' a wildcard name?
290 * 'name' is a valid name
292 * dns_name_countlabels(name) > 0
295 * TRUE The least significant label of 'name' is '*'.
296 * FALSE The least significant label of 'name' is not '*'.
300 dns_name_hash(dns_name_t *name, isc_boolean_t case_sensitive);
302 * Provide a hash value for 'name'.
304 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
305 * case will have the same hash value.
308 * 'name' is a valid name
315 dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive);
317 * Provide a hash value for 'name'. Unlike dns_name_hash(), this function
318 * always takes into account of the entire name to calculate the hash value.
320 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
321 * case will have the same hash value.
324 * 'name' is a valid name
331 dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive);
333 * Provide a hash value for 'name', where the hash value is the sum
334 * of the hash values of each label.
336 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
337 * case will have the same hash value.
340 * 'name' is a valid name
351 dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2,
352 int *orderp, unsigned int *nlabelsp);
354 * Determine the relative ordering under the DNSSEC order relation of
355 * 'name1' and 'name2', and also determine the hierarchical
356 * relationship of the names.
358 * Note: It makes no sense for one of the names to be relative and the
359 * other absolute. If both names are relative, then to be meaningfully
360 * compared the caller must ensure that they are both relative to the
364 * 'name1' is a valid name
366 * dns_name_countlabels(name1) > 0
368 * 'name2' is a valid name
370 * dns_name_countlabels(name2) > 0
372 * orderp and nlabelsp are valid pointers.
374 * Either name1 is absolute and name2 is absolute, or neither is.
378 * *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if
381 * *nlabelsp is the number of common significant labels.
384 * dns_namereln_none There's no hierarchical relationship
385 * between name1 and name2.
386 * dns_namereln_contains name1 properly contains name2; i.e.
387 * name2 is a proper subdomain of name1.
388 * dns_namereln_subdomain name1 is a proper subdomain of name2.
389 * dns_namereln_equal name1 and name2 are equal.
390 * dns_namereln_commonancestor name1 and name2 share a common
395 dns_name_compare(const dns_name_t *name1, const dns_name_t *name2);
397 * Determine the relative ordering under the DNSSEC order relation of
398 * 'name1' and 'name2'.
400 * Note: It makes no sense for one of the names to be relative and the
401 * other absolute. If both names are relative, then to be meaningfully
402 * compared the caller must ensure that they are both relative to the
406 * 'name1' is a valid name
408 * 'name2' is a valid name
410 * Either name1 is absolute and name2 is absolute, or neither is.
413 * < 0 'name1' is less than 'name2'
414 * 0 'name1' is equal to 'name2'
415 * > 0 'name1' is greater than 'name2'
419 dns_name_equal(const dns_name_t *name1, const dns_name_t *name2);
421 * Are 'name1' and 'name2' equal?
424 * Because it only needs to test for equality, dns_name_equal() can be
425 * significantly faster than dns_name_fullcompare() or dns_name_compare().
427 * Offsets tables are not used in the comparision.
429 * It makes no sense for one of the names to be relative and the
430 * other absolute. If both names are relative, then to be meaningfully
431 * compared the caller must ensure that they are both relative to the
435 * 'name1' is a valid name
437 * 'name2' is a valid name
439 * Either name1 is absolute and name2 is absolute, or neither is.
442 * ISC_TRUE 'name1' and 'name2' are equal
443 * ISC_FALSE 'name1' and 'name2' are not equal
447 dns_name_rdatacompare(const dns_name_t *name1, const dns_name_t *name2);
449 * Compare two names as if they are part of rdata in DNSSEC canonical
453 * 'name1' is a valid absolute name
455 * dns_name_countlabels(name1) > 0
457 * 'name2' is a valid absolute name
459 * dns_name_countlabels(name2) > 0
462 * < 0 'name1' is less than 'name2'
463 * 0 'name1' is equal to 'name2'
464 * > 0 'name1' is greater than 'name2'
468 dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2);
470 * Is 'name1' a subdomain of 'name2'?
473 * name1 is a subdomain of name2 if name1 is contained in name2, or
474 * name1 equals name2.
476 * It makes no sense for one of the names to be relative and the
477 * other absolute. If both names are relative, then to be meaningfully
478 * compared the caller must ensure that they are both relative to the
482 * 'name1' is a valid name
484 * 'name2' is a valid name
486 * Either name1 is absolute and name2 is absolute, or neither is.
489 * TRUE 'name1' is a subdomain of 'name2'
490 * FALSE 'name1' is not a subdomain of 'name2'
494 dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname);
496 * Does 'name' match the wildcard specified in 'wname'?
499 * name matches the wildcard specified in wname if all labels
500 * following the wildcard in wname are identical to the same number
501 * of labels at the end of name.
503 * It makes no sense for one of the names to be relative and the
504 * other absolute. If both names are relative, then to be meaningfully
505 * compared the caller must ensure that they are both relative to the
509 * 'name' is a valid name
511 * dns_name_countlabels(name) > 0
513 * 'wname' is a valid name
515 * dns_name_countlabels(wname) > 0
517 * dns_name_iswildcard(wname) is true
519 * Either name is absolute and wname is absolute, or neither is.
522 * TRUE 'name' matches the wildcard specified in 'wname'
523 * FALSE 'name' does not match the wildcard specified in 'wname'
531 dns_name_countlabels(const dns_name_t *name);
533 * How many labels does 'name' have?
536 * In this case, as in other places, a 'label' is an ordinary label.
539 * 'name' is a valid name
542 * The result is <= 128.
545 * The number of labels in 'name'.
549 dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label);
551 * Make 'label' refer to the 'n'th least significant label of 'name'.
554 * Numbering starts at 0.
556 * Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
559 * 'label' refers to the same memory as 'name', so 'name' must not
560 * be changed while 'label' is still in use.
563 * n < dns_name_countlabels(name)
567 dns_name_getlabelsequence(const dns_name_t *source, unsigned int first,
568 unsigned int n, dns_name_t *target);
570 * Make 'target' refer to the 'n' labels including and following 'first'
574 * Numbering starts at 0.
576 * Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
579 * 'target' refers to the same memory as 'source', so 'source'
580 * must not be changed while 'target' is still in use.
583 * 'source' and 'target' are valid names.
585 * first < dns_name_countlabels(name)
587 * first + n <= dns_name_countlabels(name)
592 dns_name_clone(const dns_name_t *source, dns_name_t *target);
594 * Make 'target' refer to the same name as 'source'.
598 * 'target' refers to the same memory as 'source', so 'source'
599 * must not be changed while 'target' is still in use.
601 * This call is functionally equivalent to:
603 * dns_name_getlabelsequence(source, 0,
604 * dns_name_countlabels(source),
607 * but is more efficient. Also, dns_name_clone() works even if 'source'
612 * 'source' is a valid name.
614 * 'target' is a valid name that is not read-only.
622 dns_name_fromregion(dns_name_t *name, const isc_region_t *r);
624 * Make 'name' refer to region 'r'.
627 * If the conversion encounters a root label before the end of the
628 * region the conversion stops and the length is set to the length
629 * so far converted. A maximum of 255 bytes is converted.
632 * The data in 'r' is a sequence of one or more type 00 or type 01000001
637 dns_name_toregion(dns_name_t *name, isc_region_t *r);
639 * Make 'r' refer to 'name'.
643 * 'name' is a valid name.
645 * 'r' is a valid region.
649 dns_name_fromwire(dns_name_t *name, isc_buffer_t *source,
650 dns_decompress_t *dctx, unsigned int options,
651 isc_buffer_t *target);
653 * Copy the possibly-compressed name at source (active region) into target,
657 * Decompression policy is controlled by 'dctx'.
659 * If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be
660 * downcased when they are copied into 'target'.
666 * This routine will often be used when 'source' contains raw network
667 * data. A programming error in this routine could result in a denial
668 * of service, or in the hijacking of the server.
672 * 'name' is a valid name.
674 * 'source' is a valid buffer and the first byte of the active
675 * region should be the first byte of a DNS wire format domain name.
677 * 'target' is a valid buffer or 'target' is NULL and 'name' has
678 * a dedicated buffer.
680 * 'dctx' is a valid decompression context.
684 * If result is success:
685 * If 'target' is not NULL, 'name' is attached to it.
687 * Uppercase letters are downcased in the copy iff
688 * DNS_NAME_DOWNCASE is set in options.
690 * The current location in source is advanced, and the used space
691 * in target is updated.
695 * Bad Form: Label Length
696 * Bad Form: Unknown Label Type
697 * Bad Form: Name Length
698 * Bad Form: Compression type not allowed
699 * Bad Form: Bad compression pointer
700 * Bad Form: Input too short
701 * Resource Limit: Too many compression pointers
702 * Resource Limit: Not enough space in buffer
706 dns_name_towire(const dns_name_t *name, dns_compress_t *cctx,
707 isc_buffer_t *target);
709 * Convert 'name' into wire format, compressing it as specified by the
710 * compression context 'cctx', and storing the result in 'target'.
713 * If the compression context allows global compression, then the
714 * global compression table may be updated.
717 * 'name' is a valid name
719 * dns_name_countlabels(name) > 0
721 * dns_name_isabsolute(name) == TRUE
723 * target is a valid buffer.
725 * Any offsets specified in a global compression table are valid
730 * If the result is success:
732 * The used space in target is updated.
736 * Resource Limit: Not enough space in buffer
740 dns_name_fromtext(dns_name_t *name, isc_buffer_t *source,
741 dns_name_t *origin, unsigned int options,
742 isc_buffer_t *target);
744 * Convert the textual representation of a DNS name at source
745 * into uncompressed wire form stored in target.
748 * Relative domain names will have 'origin' appended to them
749 * unless 'origin' is NULL, in which case relative domain names
750 * will remain relative.
752 * If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters
753 * in 'source' will be downcased when they are copied into 'target'.
757 * 'name' is a valid name.
759 * 'source' is a valid buffer.
761 * 'target' is a valid buffer or 'target' is NULL and 'name' has
762 * a dedicated buffer.
766 * If result is success:
767 * If 'target' is not NULL, 'name' is attached to it.
769 * Uppercase letters are downcased in the copy iff
770 * DNS_NAME_DOWNCASE is set in 'options'.
772 * The current location in source is advanced, and the used space
773 * in target is updated.
780 * (DNS_R_BADBITSTRING: should not be returned)
781 * (DNS_R_BITSTRINGTOOLONG: should not be returned)
782 * DNS_R_BADDOTTEDQUAD
784 * ISC_R_UNEXPECTEDEND
788 dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot,
789 isc_buffer_t *target);
791 * Convert 'name' into text format, storing the result in 'target'.
794 * If 'omit_final_dot' is true, then the final '.' in absolute
795 * names other than the root name will be omitted.
797 * If dns_name_countlabels == 0, the name will be "@", representing the
798 * current origin as described by RFC 1035.
800 * The name is not NUL terminated.
804 * 'name' is a valid name
806 * 'target' is a valid buffer.
808 * if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE
812 * If the result is success:
814 * The used space in target is updated.
821 #define DNS_NAME_MAXTEXT 1023
823 * The maximum length of the text representation of a domain
824 * name as generated by dns_name_totext(). This does not
825 * include space for a terminating NULL.
827 * This definition is conservative - the actual maximum
828 * is 1004, derived as follows:
830 * A backslash-decimal escaped character takes 4 bytes.
831 * A wire-encoded name can be up to 255 bytes and each
832 * label is one length byte + at most 63 bytes of data.
833 * Maximizing the label lengths gives us a name of
834 * three 63-octet labels, one 61-octet label, and the
837 * 1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255
839 * When printed, this is (3 * 63 + 61) * 4
840 * bytes for the escaped label data + 4 bytes for the
841 * dot terminating each label = 1004 bytes total.
845 dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot,
846 isc_buffer_t *target);
848 * Convert 'name' into an alternate text format appropriate for filenames,
849 * storing the result in 'target'. The name data is downcased, guaranteeing
850 * that the filename does not depend on the case of the converted name.
853 * If 'omit_final_dot' is true, then the final '.' in absolute
854 * names other than the root name will be omitted.
856 * The name is not NUL terminated.
860 * 'name' is a valid absolute name
862 * 'target' is a valid buffer.
866 * If the result is success:
868 * The used space in target is updated.
876 dns_name_downcase(dns_name_t *source, dns_name_t *name,
877 isc_buffer_t *target);
883 * 'source' and 'name' are valid names.
885 * If source == name, then
887 * 'source' must not be read-only
891 * 'target' is a valid buffer or 'target' is NULL and
892 * 'name' has a dedicated buffer.
898 * Note: if source == name, then the result will always be ISC_R_SUCCESS.
902 dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix,
903 dns_name_t *name, isc_buffer_t *target);
905 * Concatenate 'prefix' and 'suffix'.
909 * 'prefix' is a valid name or NULL.
911 * 'suffix' is a valid name or NULL.
913 * 'name' is a valid name or NULL.
915 * 'target' is a valid buffer or 'target' is NULL and 'name' has
916 * a dedicated buffer.
918 * If 'prefix' is absolute, 'suffix' must be NULL or the empty name.
923 * If 'target' is not NULL and 'name' is not NULL, then 'name'
926 * The used space in target is updated.
935 dns_name_split(dns_name_t *name, unsigned int suffixlabels,
936 dns_name_t *prefix, dns_name_t *suffix);
939 * Split 'name' into two pieces on a label boundary.
942 * 'name' is split such that 'suffix' holds the most significant
943 * 'suffixlabels' labels. All other labels are stored in 'prefix'.
945 * Copying name data is avoided as much as possible, so 'prefix'
946 * and 'suffix' will end up pointing at the data for 'name'.
948 * It is legitimate to pass a 'prefix' or 'suffix' that has
949 * its name data stored someplace other than the dedicated buffer.
950 * This is useful to avoid name copying in the calling function.
952 * It is also legitimate to pass a 'prefix' or 'suffix' that is
953 * the same dns_name_t as 'name'.
956 * 'name' is a valid name.
958 * 'suffixlabels' cannot exceed the number of labels in 'name'.
960 * 'prefix' is a valid name or NULL, and cannot be read-only.
962 * 'suffix' is a valid name or NULL, and cannot be read-only.
964 * If non-NULL, 'prefix' and 'suffix' must have dedicated buffers.
966 * 'prefix' and 'suffix' cannot point to the same buffer.
971 * If 'prefix' is not NULL it will contain the least significant
974 * If 'suffix' is not NULL it will contain the most significant
975 * labels. dns_name_countlabels(suffix) will be equal to
979 * Either 'prefix' or 'suffix' is invalidated (depending
980 * on which one the problem was encountered with).
983 * ISC_R_SUCCESS No worries. (This function should always success).
987 dns_name_dup(const dns_name_t *source, isc_mem_t *mctx, dns_name_t *target);
989 * Make 'target' a dynamically allocated copy of 'source'.
993 * 'source' is a valid non-empty name.
995 * 'target' is a valid name that is not read-only.
997 * 'mctx' is a valid memory context.
1001 dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx,
1002 dns_name_t *target);
1004 * Make 'target' a read-only dynamically allocated copy of 'source'.
1005 * 'target' will also have a dynamically allocated offsets table.
1009 * 'source' is a valid non-empty name.
1011 * 'target' is a valid name that is not read-only.
1013 * 'target' has no offsets table.
1015 * 'mctx' is a valid memory context.
1019 dns_name_free(dns_name_t *name, isc_mem_t *mctx);
1025 * 'name' is a valid name created previously in 'mctx' by dns_name_dup().
1027 * 'mctx' is a valid memory context.
1031 * All dynamic resources used by 'name' are freed and the name is
1036 dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg);
1038 * Send 'name' in DNSSEC canonical form to 'digest'.
1042 * 'name' is a valid name.
1044 * 'digest' is a valid dns_digestfunc_t.
1048 * If successful, the DNSSEC canonical form of 'name' will have been
1051 * If digest() returns something other than ISC_R_SUCCESS, that result
1052 * will be returned as the result of dns_name_digest().
1058 * Many other results are possible if not successful.
1063 dns_name_dynamic(dns_name_t *name);
1065 * Returns whether there is dynamic memory associated with this name.
1069 * 'name' is a valid name.
1073 * 'ISC_TRUE' if the name is dynamic othewise 'ISC_FALSE'.
1077 dns_name_print(dns_name_t *name, FILE *stream);
1079 * Print 'name' on 'stream'.
1083 * 'name' is a valid name.
1085 * 'stream' is a valid stream.
1091 * Any error that dns_name_totext() can return.
1095 dns_name_format(dns_name_t *name, char *cp, unsigned int size);
1097 * Format 'name' as text appropriate for use in log messages.
1099 * Store the formatted name at 'cp', writing no more than
1100 * 'size' bytes. The resulting string is guaranteed to be
1103 * The formatted name will have a terminating dot only if it is
1106 * This function cannot fail, instead any errors are indicated
1107 * in the returned text.
1111 * 'name' is a valid name.
1113 * 'cp' points a valid character array of size 'size'.
1119 #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1)
1121 * Suggested size of buffer passed to dns_name_format().
1122 * Includes space for the terminating NULL.
1126 dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target);
1128 * Makes 'dest' refer to a copy of the name in 'source'. The data are
1129 * either copied to 'target' or the dedicated buffer in 'dest'.
1132 * 'source' is a valid name.
1134 * 'dest' is an initialized name with a dedicated buffer.
1136 * 'target' is NULL or an initialized buffer.
1138 * Either dest has a dedicated buffer or target != NULL.
1142 * On success, the used space in target is updated.
1150 dns_name_ishostname(const dns_name_t *name, isc_boolean_t wildcard);
1152 * Return if 'name' is a valid hostname. RFC 952 / RFC 1123.
1153 * If 'wildcard' is ISC_TRUE then allow the first label of name to
1155 * The root is also accepted.
1158 * 'name' to be valid.
1163 dns_name_ismailbox(const dns_name_t *name);
1165 * Return if 'name' is a valid mailbox. RFC 821.
1168 * 'name' to be valid.
1174 *** High Peformance Macros
1178 * WARNING: Use of these macros by applications may require recompilation
1179 * of the application in some situations where calling the function
1182 * WARNING: No assertion checking is done for these macros.
1185 #define DNS_NAME_INIT(n, o) \
1187 (n)->magic = DNS_NAME_MAGIC; \
1188 (n)->ndata = NULL; \
1191 (n)->attributes = 0; \
1192 (n)->offsets = (o); \
1193 (n)->buffer = NULL; \
1194 ISC_LINK_INIT((n), link); \
1195 ISC_LIST_INIT((n)->list); \
1198 #define DNS_NAME_RESET(n) \
1200 (n)->ndata = NULL; \
1203 (n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \
1204 if ((n)->buffer != NULL) \
1205 isc_buffer_clear((n)->buffer); \
1208 #define DNS_NAME_SETBUFFER(n, b) \
1211 #define DNS_NAME_ISABSOLUTE(n) \
1212 (((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? ISC_TRUE : ISC_FALSE)
1214 #define DNS_NAME_COUNTLABELS(n) \
1217 #define DNS_NAME_TOREGION(n, r) \
1219 (r)->base = (n)->ndata; \
1220 (r)->length = (n)->length; \
1223 #define DNS_NAME_SPLIT(n, l, p, s) \
1225 dns_name_t *_n = (n); \
1226 dns_name_t *_p = (p); \
1227 dns_name_t *_s = (s); \
1228 unsigned int _l = (l); \
1230 dns_name_getlabelsequence(_n, 0, _n->labels - _l, _p); \
1232 dns_name_getlabelsequence(_n, _n->labels - _l, _l, _s); \
1235 #ifdef DNS_NAME_USEINLINE
1237 #define dns_name_init(n, o) DNS_NAME_INIT(n, o)
1238 #define dns_name_reset(n) DNS_NAME_RESET(n)
1239 #define dns_name_setbuffer(n, b) DNS_NAME_SETBUFFER(n, b)
1240 #define dns_name_countlabels(n) DNS_NAME_COUNTLABELS(n)
1241 #define dns_name_isabsolute(n) DNS_NAME_ISABSOLUTE(n)
1242 #define dns_name_toregion(n, r) DNS_NAME_TOREGION(n, r)
1243 #define dns_name_split(n, l, p, s) DNS_NAME_SPLIT(n, l, p, s)
1245 #endif /* DNS_NAME_USEINLINE */
1247 #endif /* DNS_NAME_H */