libnl 1.1
lib/doc.c
00001 /*
00002  * lib/doc.c            Documentation Purpose
00003  *
00004  *      This library is free software; you can redistribute it and/or
00005  *      modify it under the terms of the GNU Lesser General Public
00006  *      License as published by the Free Software Foundation version 2.1
00007  *      of the License.
00008  *
00009  * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
00010  */
00011 
00012 /**
00013  * @mainpage
00014  *
00015  * @section remarks Remarks
00016  *
00017  * @subsection cache_alloc Allocation of Caches
00018  *
00019  * Almost all subsystem provide a function to allocate a new cache
00020  * of some form. The function usually looks like this:
00021  * @code
00022  * struct nl_cache *<object name>_alloc_cache(struct nl_handle *handle)
00023  * @endcode
00024  *
00025  * These functions allocate a new cache for the own object type,
00026  * initializes it properly and updates it to represent the current
00027  * state of their master, e.g. a link cache would include all
00028  * links currently configured in the kernel.
00029  *
00030  * Some of the allocation functions may take additional arguments
00031  * to further specify what will be part of the cache.
00032  *
00033  * All such functions return a newly allocated cache or NULL
00034  * in case of an error.
00035  *
00036  * @subsection addr Setting of Addresses
00037  * @code
00038  * int <object name>_set_addr(struct nl_object *, struct nl_addr *)
00039  * @endcode
00040  *
00041  * All attribute functions avaiable for assigning addresses to objects
00042  * take a struct nl_addr argument. The provided address object is
00043  * validated against the address family of the object if known already.
00044  * The assignment fails if the address families mismatch. In case the
00045  * address family has not been specified yet, the address family of
00046  * the new address is elected to be the new requirement.
00047  *
00048  * The function will acquire a new reference on the address object
00049  * before assignment, the caller is NOT responsible for this.
00050  *
00051  * All functions return 0 on success or a negative error code.
00052  *
00053  * @subsection flags Flags to Character StringTranslations
00054  * All functions converting a set of flags to a character string follow
00055  * the same principles, therefore, the following information applies
00056  * to all functions convertings flags to a character string and vice versa.
00057  *
00058  * @subsubsection flags2str Flags to Character String
00059  * @code
00060  * char *<object name>_flags2str(int flags, char *buf, size_t len)
00061  * @endcode
00062  * @arg flags           Flags.
00063  * @arg buf             Destination buffer.
00064  * @arg len             Buffer length.
00065  *
00066  * Converts the specified flags to a character string separated by
00067  * commas and stores it in the specified destination buffer.
00068  *
00069  * @return The destination buffer
00070  *
00071  * @subsubsection str2flags Character String to Flags
00072  * @code
00073  * int <object name>_str2flags(const char *name)
00074  * @endcode
00075  * @arg name            Name of flag.
00076  *
00077  * Converts the provided character string specifying a flag
00078  * to the corresponding numeric value.
00079  *
00080  * @return Link flag or a negative value if none was found.
00081  *
00082  * @subsubsection type2str Type to Character String
00083  * @code
00084  * char *<object name>_<type>2str(int type, char *buf, size_t len)
00085  * @endcode
00086  * @arg type            Type as numeric value
00087  * @arg buf             Destination buffer.
00088  * @arg len             Buffer length.
00089  *
00090  * Converts an identifier (type) to a character string and stores
00091  * it in the specified destination buffer.
00092  *
00093  * @return The destination buffer or the type encoded in hexidecimal
00094  *         form if the identifier is unknown.
00095  *
00096  * @subsubsection str2type Character String to Type
00097  * @code
00098  * int <object name>_str2<type>(const char *name)
00099  * @endcode
00100  * @arg name            Name of identifier (type).
00101  *
00102  * Converts the provided character string specifying a identifier
00103  * to the corresponding numeric value.
00104  *
00105  * @return Identifier as numeric value or a negative value if none was found.
00106  */