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 */