name.h

bind-3.2.

 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE
 */

#define DNS_NAME_MAXTEXT 1023
/*
 * The maximum length of the text representation of a domain
 * name as generated by dns_name_totext().  This does not
 * include space for a terminating NULL.
 *
 * This definition is conservative - the actual maximum 
 * is 1004, derived as follows:
 *
 *   A backslash-decimal escaped character takes 4 bytes.
 *   A wire-encoded name can be up to 255 bytes and each
 *   label is one length byte + at most 63 bytes of data.
 *   Maximizing the label lengths gives us a name of
 *   three 63-octet labels, one 61-octet label, and the
 *   root label:
 *
 *      1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255
 *
 *   When printed, this is (3 * 63 + 61) * 4
 *   bytes for the escaped label data + 4 bytes for the
 *   dot terminating each label = 1004 bytes total.
 */

isc_result_t
dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot,
			isc_buffer_t *target);
/*
 * Convert 'name' into an alternate text format appropriate for filenames,
 * storing the result in 'target'.  The name data is downcased, guaranteeing
 * that the filename does not depend on the case of the converted name.
 *
 * Notes:
 *	If 'omit_final_dot' is true, then the final '.' in absolute
 *	names other than the root name will be omitted.
 *
 *	The name is not NUL terminated.
 *
 * Requires:
 *
 *	'name' is a valid absolute name
 *
 *	'target' is a valid buffer.
 *
 * Ensures:
 *
 *	If the result is success:
 *
 *		The used space in target is updated.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE
 */

isc_result_t
dns_name_downcase(dns_name_t *source, dns_name_t *name,
		  isc_buffer_t *target);
/*
 * Downcase 'source'.
 *
 * Requires:
 *
 *	'source' and 'name' are valid names.
 *
 *	If source == name, then
 *
 *		'source' must not be read-only
 *
 *	Otherwise,
 *
 *		'target' is a valid buffer or 'target' is NULL and
 *		'name' has a dedicated buffer.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE
 *
 * Note: if source == name, then the result will always be ISC_R_SUCCESS.
 */

isc_result_t
dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix,
		     dns_name_t *name, isc_buffer_t *target);
/*
 *	Concatenate 'prefix' and 'suffix'.
 *
 * Requires:
 *
 *	'prefix' is a valid name or NULL.
 *
 *	'suffix' is a valid name or NULL.
 *
 *	'name' is a valid name or NULL.
 *
 *	'target' is a valid buffer or 'target' is NULL and 'name' has
 *	a dedicated buffer.
 *
 *	If 'prefix' is absolute, 'suffix' must be NULL or the empty name.
 *
 * Ensures:
 *
 *	On success,
 *	 	If 'target' is not NULL and 'name' is not NULL, then 'name'
 *		is attached to it.
 *
 *		Any bitstring labels are in canonical form.
 *
 *		The used space in target is updated.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE
 *	DNS_R_NAMETOOLONG
 */

isc_result_t
dns_name_split(dns_name_t *name,
	       unsigned int suffixlabels, unsigned int nbits,
	       dns_name_t *prefix, dns_name_t *suffix);
/*
 *
 * Split 'name' into two pieces on a label or bitlabel boundary.
 *
 * Notes:
 *      'name' is split such that 'suffix' holds the most significant
 *      'suffixlabels' labels, except that if the least significant
 *      suffix label is a bitstring label, then only the 'nbits' most
 *      significant bits of that label are included in 'suffix'.  All 
 *      other labels and bits are stored in 'prefix'.
 *
 *	Copying name data is avoided as much as possible, so 'prefix'
 *	and 'suffix' will usually end up pointing at the data for 'name',
 *	except when 'nbits' > 0.  The name data is copied to the
 *	the dedicated buffers when splitting on bitlabel boundaries
 *	because of the bit fiddling that must be done.
 *
 *	It is legitimate to pass a 'prefix' or 'suffix' that has
 *	its name data stored someplace other than the dedicated buffer.
 *	This is useful to avoid name copying in the calling function.
 *
 *	It is also legitimate to pass a 'prefix' or 'suffix' that is
 *	the same dns_name_t as 'name', but note well the requirement
 *	below if splitting on a bitlabel boundary.
 *
 * Requires:
 *	'name' is a valid name.
 *
 * 	'suffixlabels' cannot exceed the number of labels in 'name'.
 *
 *	'nbits' can be greater than zero only when the least significant
 *	label of 'suffix' is a bitstring label.
 *
 *	'nbits' cannot exceed the number of bits in the bitstring label.
 *
 *	'prefix' is a valid name or NULL, and cannot be read-only.
 *
 *	'suffix' is a valid name or NULL, and cannot be read-only.
 *
 *	If non-NULL, 'prefix' and 'suffix' must have dedicated buffers.
 *
 *	'prefix' and 'suffix' cannot point to the same buffer.
 *
 *	If 'nbits' > 0 and 'prefix' and 'suffix' are both non-NULL,
 *	the buffer for 'prefix' cannot be storing the labels for 'name'.
 *
 * Ensures:
 *
 *	On success:
 *		If 'prefix' is not NULL it will contain the least significant
 *		labels and bits.
 *
 *		If 'suffix' is not NULL it will contain the most significant
 *		labels and bits.  dns_name_countlabels(suffix) will be
 *		equal to suffixlabels.
 *
 *	On failure:
 *		Either 'prefix' or 'suffix' is invalidated (depending
 *		on which one the problem was encountered with).
 *
 * Returns:
 *	ISC_R_SUCCESS	No worries.
 *	ISC_R_NOSPACE	An attempt was made to split a name on a bitlabel
 *			boundary but either 'prefix' or 'suffix' did not
 *			have enough room to receive the split name.
 */

isc_result_t
dns_name_splitatdepth(dns_name_t *name, unsigned int depth,
		      dns_name_t *prefix, dns_name_t *suffix);
/*
 * Split 'name' into two pieces at a certain depth.
 *
 * Requires:
 *	'name' is a valid non-empty name.
 *
 *	depth > 0
 *
 *	depth <= dns_name_depth(name)
 *
 *	The preconditions of dns_name_split() apply to 'prefix' and 'suffix'.
 *
 * Ensures:
 *
 *	On success:
 *		If 'prefix' is not NULL it will contain the least significant
 *		labels and bits.
 *
 *		If 'suffix' is not NULL it will contain the most significant
 *		labels and bits.  dns_name_countlabels(suffix) will be
 *		equal to suffixlabels.
 *
 *	On failure:
 *		Either 'prefix' or 'suffix' is invalidated (depending
 *		on which one the problem was encountered with).
 *
 * Returns:
 *	The possible result codes are the same as those of dns_name_split().
 */

isc_result_t
dns_name_dup(dns_name_t *source, isc_mem_t *mctx, dns_name_t *target);
/*
 * Make 'target' a dynamically allocated copy of 'source'.
 *
 * Requires:
 *
 *	'source' is a valid non-empty name.
 *
 *	'target' is a valid name that is not read-only.
 *
 *	'mctx' is a valid memory context.
 */

isc_result_t
dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx,
			dns_name_t *target);
/*
 * Make 'target' a read-only dynamically allocated copy of 'source'.
 * 'target' will also have a dynamically allocated offsets table.
 *
 * Requires:
 *
 *	'source' is a valid non-empty name.
 *
 *	'target' is a valid name that is not read-only.
 *
 *	'target' has no offsets table.
 *
 *	'mctx' is a valid memory context.
 */

void
dns_name_free(dns_name_t *name, isc_mem_t *mctx);
/*
 * Free 'name'.
 *
 * Requires:
 *
 *	'name' is a valid name created previously in 'mctx' by dns_name_dup().
 *
 *	'mctx' is a valid memory context.
 *
 * Ensures:
 *
 *	All dynamic resources used by 'name' are freed and the name is
 *	invalidated.
 */

isc_result_t
dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg);
/*
 * Send 'name' in DNSSEC canonical form to 'digest'.
 *
 * Requires:
 *
 *	'name' is a valid name.
 *
 *	'digest' is a valid dns_digestfunc_t.
 *
 * Ensures:
 *
 *	If successful, the DNSSEC canonical form of 'name' will have been
 *	sent to 'digest'.
 *
 *	If digest() returns something other than ISC_R_SUCCESS, that result
 *	will be returned as the result of dns_name_digest().
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *
 *	Many other results are possible if not successful.
 *
 */

isc_boolean_t
dns_name_dynamic(dns_name_t *name);
/*
 * Returns whether there is dynamic memory associated with this name.
 *
 * Requires:
 *
 *	'name' is a valid name.
 *
 * Returns:
 *
 *	'ISC_TRUE' if the name is dynamic othewise 'ISC_FALSE'.
 */

isc_result_t
dns_name_print(dns_name_t *name, FILE *stream);
/*
 * Print 'name' on 'stream'.
 *
 * Requires:
 *
 *	'name' is a valid name.
 *
 *	'stream' is a valid stream.
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *
 *	Any error that dns_name_totext() can return.
 */

void
dns_name_format(dns_name_t *name, char *cp, unsigned int size);
/*
 * Format 'name' as text appropriate for use in log messages.
 *
 * Store the formatted name at 'cp', writing no more than
 * 'size' bytes.  The resulting string is guaranteed to be
 * null terminated.
 *
 * The formatted name will have a terminating dot only if it is
 * the root.
 *
 * This function cannot fail, instead any errors are indicated
 * in the returned text.
 *
 * Requires:
 *
 *	'name' is a valid name.
 *
 *	'cp' points a valid character array of size 'size'.
 *
 *	'size' > 0.
 *
 */

#define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1)
/*
 * Suggested size of buffer passed to dns_name_format().
 * Includes space for the terminating NULL.
 */

isc_result_t
dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target);
/*
 * Makes 'dest' refer to a copy of the name in 'source'.  The data are
 * either copied to 'target' or the dedicated buffer in 'dest'.
 *
 * Requires:
 * 	'source' is a valid name.
 *
 * 	'dest' is an initialized name with a dedicated buffer.
 *
 * 	'target' is NULL or an initialized buffer.
 *
 * 	Either dest has a dedicated buffer or target != NULL.
 *
 * Ensures:
 *
 *	On success, the used space in target is updated.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOSPACE
 */

ISC_LANG_ENDDECLS

/***
 *** High Peformance Macros
 ***/

/*
 * WARNING:  Use of these macros by applications may require recompilation
 *           of the application in some situations where calling the function
 *           would not.
 *
 * WARNING:  No assertion checking is done for these macros.
 */

#define DNS_NAME_INIT(n, o) \
do { \
	(n)->magic = DNS_NAME_MAGIC; \
	(n)->ndata = NULL; \
	(n)->length = 0; \
	(n)->labels = 0; \
	(n)->attributes = 0; \
	(n)->offsets = (o); \
	(n)->buffer = NULL; \
	ISC_LINK_INIT((n), link); \
	ISC_LIST_INIT((n)->list); \
} while (0)

#define DNS_NAME_RESET(n) \
do { \
	(n)->ndata = NULL; \
	(n)->length = 0; \
	(n)->labels = 0; \
	(n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \
	if ((n)->buffer != NULL) \
		isc_buffer_clear((n)->buffer); \
} while (0)

#define DNS_NAME_SETBUFFER(n, b) \
	(n)->buffer = (b)

#define DNS_NAME_ISABSOLUTE(n) \
	(((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? ISC_TRUE : ISC_FALSE)

#define DNS_NAME_COUNTLABELS(n) \
	((n)->labels)

#define DNS_NAME_TOREGION(n, r) \
do { \
	(r)->base = (n)->ndata; \
	(r)->length = (n)->length; \
} while (0);


#ifdef DNS_NAME_USEINLINE

#define dns_name_init(n, o)		DNS_NAME_INIT(n, o)
#define dns_name_reset(n)		DNS_NAME_RESET(n)
#define dns_name_setbuffer(n, b)	DNS_NAME_SETBUFFER(n, b)
#define dns_name_countlabels(n)		DNS_NAME_COUNTLABELS(n)
#define dns_name_isabsolute(n)		DNS_NAME_ISABSOLUTE(n)
#define dns_name_toregion(n, r)		DNS_NAME_TOREGION(n, r)

#endif /* DNS_NAME_USEINLINE */

#endif /* DNS_NAME_H */