From: Jelmer Vernooij Date: Tue, 28 Feb 2006 13:12:39 +0000 (+0000) Subject: r13752: Add doxyfile and fix formatting of comments. Current output is available... X-Git-Tag: samba-misc-tags/initial-v4-0-unstable~5431 X-Git-Url: http://git.samba.org/?p=samba.git;a=commitdiff_plain;h=90812203df151a5e62394306827c72adfe13c63c r13752: Add doxyfile and fix formatting of comments. Current output is available at samba.org/~jelmer/util-api/ --- diff --git a/source/lib/util/Doxyfile b/source/lib/util/Doxyfile new file mode 100644 index 00000000000..7205513eb19 --- /dev/null +++ b/source/lib/util/Doxyfile @@ -0,0 +1,1229 @@ +# Doxyfile 1.4.4 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = SAMBA_UTIL + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = apidocs + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, +# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, +# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, +# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, +# Swedish, and Ukrainian. + +OUTPUT_LANGUAGE = English + +# This tag can be used to specify the encoding used in the generated output. +# The encoding is not always determined by the language that is chosen, +# but also whether or not the output is meant for Windows or non-Windows users. +# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES +# forces the Windows encoding (this is the default for the Windows binary), +# whereas setting the tag to NO uses a Unix-style encoding (the default for +# all platforms other than Windows). + +USE_WINDOWS_ENCODING = NO + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = include + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like the Qt-style comments (thus requiring an +# explicit @brief command for a brief description. + +JAVADOC_AUTOBRIEF = YES + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = YES + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources +# only. Doxygen will then generate output that is more tailored for Java. +# For instance, namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is YES. + +SHOW_DIRECTORIES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from the +# version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the progam writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = . + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm + +FILE_PATTERNS = *.c byteorder.h debug.h mutex.h util.h xfile.h *.dox + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = NO + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = include/config.h include/dlinklist.h \ + include/includes.h + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = examples + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be +# generated containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = YES + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_PREDEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = NO + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = NO + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = NO + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will +# generate a call dependency graph for every global function or class method. +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = NO + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_WIDTH = 1024 + +# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height +# (in pixels) of the graphs generated by dot. If a graph becomes larger than +# this value, doxygen will try to truncate the graph, so that it fits within +# the specified constraint. Beware that most browsers cannot cope with very +# large images. + +MAX_DOT_GRAPH_HEIGHT = 1024 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that a graph may be further truncated if the graph's +# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH +# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), +# the graph is not depth-constrained. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, which results in a white background. +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO diff --git a/source/lib/util/capability.c b/source/lib/util/capability.c index 0cebd333032..ae08fab533c 100644 --- a/source/lib/util/capability.c +++ b/source/lib/util/capability.c @@ -19,6 +19,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/** + * @file + * @brief Capabilities functions + **/ + /* capabilities fns - will be needed when we enable kernel oplocks */ diff --git a/source/lib/util/data_blob.c b/source/lib/util/data_blob.c index c6471fbf540..dfcfaa41ea5 100644 --- a/source/lib/util/data_blob.c +++ b/source/lib/util/data_blob.c @@ -21,10 +21,15 @@ #include "includes.h" -/******************************************************************* +/** + * @file + * @brief Manipulation of arbitrary data blobs + **/ + +/** construct a data blob, must be freed with data_blob_free() you can pass NULL for p and get a blank data blob -*******************************************************************/ +**/ DATA_BLOB data_blob_named(const void *p, size_t length, const char *name) { DATA_BLOB ret; @@ -48,9 +53,9 @@ DATA_BLOB data_blob_named(const void *p, size_t length, const char *name) return ret; } -/******************************************************************* +/** construct a data blob, using supplied TALLOC_CTX -*******************************************************************/ +**/ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name) { DATA_BLOB ret = data_blob_named(p, length, name); @@ -62,10 +67,10 @@ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t leng } -/******************************************************************* +/** reference a data blob, to the supplied TALLOC_CTX. Returns a NULL DATA_BLOB on failure -*******************************************************************/ +**/ DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob) { DATA_BLOB ret = *blob; @@ -78,11 +83,11 @@ DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob) return ret; } -/******************************************************************* +/** construct a zero data blob, using supplied TALLOC_CTX. use this sparingly as it initialises data - better to initialise yourself if you want specific data in the blob -*******************************************************************/ +**/ DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length) { DATA_BLOB blob = data_blob_talloc(mem_ctx, NULL, length); @@ -90,9 +95,9 @@ DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length) return blob; } -/******************************************************************* +/** free a data blob -*******************************************************************/ +**/ void data_blob_free(DATA_BLOB *d) { if (d) { @@ -102,9 +107,9 @@ void data_blob_free(DATA_BLOB *d) } } -/******************************************************************* +/** clear a DATA_BLOB's contents -*******************************************************************/ +**/ void data_blob_clear(DATA_BLOB *d) { if (d->data) { @@ -112,9 +117,9 @@ void data_blob_clear(DATA_BLOB *d) } } -/******************************************************************* +/** free a data blob and clear its contents -*******************************************************************/ +**/ void data_blob_clear_free(DATA_BLOB *d) { data_blob_clear(d); @@ -122,9 +127,9 @@ void data_blob_clear_free(DATA_BLOB *d) } -/******************************************************************* +/** check if two data blobs are equal -*******************************************************************/ +**/ BOOL data_blob_equal(const DATA_BLOB *d1, const DATA_BLOB *d2) { if (d1->length != d2->length) { @@ -142,9 +147,9 @@ BOOL data_blob_equal(const DATA_BLOB *d1, const DATA_BLOB *d2) return False; } -/******************************************************************* +/** print the data_blob as hex string -*******************************************************************/ +**/ char *data_blob_hex_string(TALLOC_CTX *mem_ctx, DATA_BLOB *blob) { int i; @@ -161,10 +166,10 @@ char *data_blob_hex_string(TALLOC_CTX *mem_ctx, DATA_BLOB *blob) return hex_string; } -/* +/** useful for constructing data blobs in test suites, while avoiding const warnings -*/ +**/ DATA_BLOB data_blob_string_const(const char *str) { DATA_BLOB blob; @@ -182,9 +187,9 @@ DATA_BLOB data_blob_const(const void *p, size_t length) } -/* +/** realloc a data_blob -*/ +**/ NTSTATUS data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length) { blob->data = talloc_realloc_size(mem_ctx, blob->data, length); @@ -193,9 +198,9 @@ NTSTATUS data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length) return NT_STATUS_OK; } -/* +/** append some data to a data blob -*/ +**/ NTSTATUS data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, const void *p, size_t length) { diff --git a/source/lib/util/debug.c b/source/lib/util/debug.c index 9df6e573b09..3a71ed2df61 100644 --- a/source/lib/util/debug.c +++ b/source/lib/util/debug.c @@ -24,6 +24,11 @@ #include "system/time.h" #include "dynconfig.h" +/** + * @file + * @brief Debug logging + **/ + /* this global variable determines what messages are printed */ int DEBUGLEVEL; @@ -74,7 +79,7 @@ void do_debug(const char *format, ...) free(s); } -/* +/** reopen the log file (usually called because the log file name might have changed) */ void reopen_logs(void) @@ -118,7 +123,7 @@ void reopen_logs(void) } } -/* +/** control the name of the logfile and whether logging will be to stdout, stderr or a file */ @@ -133,7 +138,7 @@ void setup_logging(const char *prog_name, enum debug_logtype new_logtype) reopen_logs(); } -/* +/** return a string constant containing n tabs no more than 10 tabs are returned */ @@ -146,8 +151,8 @@ const char *do_debug_tab(uint_t n) } -/* - log/print suspicious usage - print comments and backtrace +/** + log suspicious usage - print comments and backtrace */ void log_suspicious_usage(const char *from, const char *info) { @@ -155,6 +160,12 @@ void log_suspicious_usage(const char *from, const char *info) debug_handlers.ops.log_suspicious_usage(from, info); } } + + +/** + print suspicious usage - print comments and backtrace +*/ + void print_suspicious_usage(const char* from, const char* info) { if (debug_handlers.ops.print_suspicious_usage) { @@ -195,7 +206,7 @@ void log_task_id(void) } } -/* +/** register a set of debug handlers. */ void register_debug_handlers(const char *name, struct debug_ops *ops) diff --git a/source/lib/util/fault.c b/source/lib/util/fault.c index 3670575dcc7..abe3f141ce4 100644 --- a/source/lib/util/fault.c +++ b/source/lib/util/fault.c @@ -23,6 +23,11 @@ #include "system/wait.h" #include "system/filesys.h" +/** + * @file + * @brief Fault handling + */ + /* the registered fault handler */ static struct { const char *name; @@ -38,6 +43,9 @@ static const char *progname; #include #endif +/** + * Write backtrace to debug log + */ void call_backtrace(void) { #ifdef HAVE_BACKTRACE @@ -101,9 +109,9 @@ void call_backtrace(void) #endif } -/******************************************************************* +/** Something really nasty happened - panic ! -********************************************************************/ +**/ void smb_panic(const char *why) { const char *cmd = lp_panic_action(); @@ -138,9 +146,9 @@ void smb_panic(const char *why) abort(); } -/******************************************************************* +/** report a fault -********************************************************************/ +**/ static void fault_report(int sig) { static int counter; @@ -157,9 +165,9 @@ static void fault_report(int sig) exit(1); } -/**************************************************************************** +/** catch serious errors -****************************************************************************/ +**/ static void sig_fault(int sig) { if (fault_handlers.fault_handler) { @@ -170,9 +178,9 @@ static void sig_fault(int sig) fault_report(sig); } -/******************************************************************* +/** setup our fault handlers -********************************************************************/ +**/ void fault_setup(const char *pname) { if (progname == NULL) { @@ -192,7 +200,7 @@ void fault_setup(const char *pname) #endif } -/* +/** register a fault handler. Should only be called once in the execution of smbd. */ diff --git a/source/lib/util/fsusage.c b/source/lib/util/fsusage.c index f8176725447..dde9c61eb39 100644 --- a/source/lib/util/fsusage.c +++ b/source/lib/util/fsusage.c @@ -21,6 +21,10 @@ #include "includes.h" #include "system/filesys.h" +/** + * @file + * @brief Utility functions for getting the amount of free disk space + */ /* Return the number of TOSIZE-byte blocks used by BLOCKS FROMSIZE-byte blocks, rounding away from zero. @@ -35,11 +39,13 @@ static uint64_t adjust_blocks(uint64_t blocks, uint64_t fromsize, uint64_t tosiz return (blocks + 1) / (tosize / fromsize); } -/* this does all of the system specific guff to get the free disk space. - It is derived from code in the GNU fileutils package, but has been - considerably mangled for use here - - results are returned in *dfree and *dsize, in 512 byte units +/** + * Retrieve amount of free disk space. + * this does all of the system specific guff to get the free disk space. + * It is derived from code in the GNU fileutils package, but has been + * considerably mangled for use here + * + * results are returned in *dfree and *dsize, in 512 byte units */ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize) { diff --git a/source/lib/util/genrand.c b/source/lib/util/genrand.c index 1149314d0b4..a264ac4e315 100644 --- a/source/lib/util/genrand.c +++ b/source/lib/util/genrand.c @@ -25,15 +25,20 @@ #include "system/filesys.h" #include "lib/crypto/crypto.h" +/** + * @file + * @brief Random number generation + */ + static unsigned char hash[258]; static uint32_t counter; static BOOL done_reseed = False; static void (*reseed_callback)(int *newseed); -/**************************************************************** +/** Copy any user given reseed data. -*****************************************************************/ +**/ void set_rand_reseed_callback(void (*fn)(int *)) { @@ -196,9 +201,9 @@ static int do_reseed(BOOL use_fd, int fd) return -1; } -/* +/** Interface to the (hopefully) good crypto random number generator. -*/ +**/ void generate_random_buffer(uint8_t *out, int len) { static int urand_fd = -1; @@ -242,9 +247,9 @@ void generate_random_buffer(uint8_t *out, int len) } } -/* +/** generate a single random uint32_t -*/ +**/ uint32_t generate_random(void) { uint8_t v[4]; @@ -253,9 +258,9 @@ uint32_t generate_random(void) } -/* +/** very basic password quality checker -*/ +**/ BOOL check_password_quality(const char *s) { int has_digit=0, has_capital=0, has_lower=0; @@ -273,9 +278,9 @@ BOOL check_password_quality(const char *s) return has_digit && has_lower && has_capital; } -/******************************************************************* +/** Use the random number generator to generate a random string. -********************************************************************/ +**/ char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const char *list) { diff --git a/source/lib/util/idtree.c b/source/lib/util/idtree.c index a67a80940a0..1ccf6d5e817 100644 --- a/source/lib/util/idtree.c +++ b/source/lib/util/idtree.c @@ -29,6 +29,10 @@ see the section marked "public interface" below for documentation */ +/** + * @file + */ + #include "includes.h" #define IDR_BITS 5 diff --git a/source/lib/util/module.c b/source/lib/util/module.c index 672d8df7cef..ad8afe2b16f 100644 --- a/source/lib/util/module.c +++ b/source/lib/util/module.c @@ -18,6 +18,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/** + * @file + * @brief Module initialization function handling + */ + #include "includes.h" #include "system/dir.h" diff --git a/source/lib/util/ms_fnmatch.c b/source/lib/util/ms_fnmatch.c index d44c8b87da1..a4fca4fa0a8 100644 --- a/source/lib/util/ms_fnmatch.c +++ b/source/lib/util/ms_fnmatch.c @@ -24,6 +24,10 @@ code now */ +/** + * @file + * @brief MS-style Filename matching + */ #include "includes.h" @@ -212,7 +216,7 @@ int ms_fnmatch(const char *pattern, const char *string, enum protocol_types prot } -/* a generic fnmatch function - uses for non-CIFS pattern matching */ +/** a generic fnmatch function - uses for non-CIFS pattern matching */ int gen_fnmatch(const char *pattern, const char *string) { return ms_fnmatch(pattern, string, PROTOCOL_NT1); diff --git a/source/lib/util/mutex.c b/source/lib/util/mutex.c index 480ba92cc09..79c281ff0cf 100644 --- a/source/lib/util/mutex.c +++ b/source/lib/util/mutex.c @@ -20,6 +20,11 @@ */ #include "includes.h" #include "mutex.h" + +/** + * @file + * @brief Mutex utility functions + */ /* the registered mutex handlers */ static struct { @@ -30,7 +35,7 @@ static struct { /* read/write lock routines */ -/* +/** register a set of mutex/rwlock handlers. Should only be called once in the execution of smbd. */ diff --git a/source/lib/util/pidfile.c b/source/lib/util/pidfile.c index 9a7c197f700..7f56fa5641e 100644 --- a/source/lib/util/pidfile.c +++ b/source/lib/util/pidfile.c @@ -27,8 +27,15 @@ #define O_NONBLOCK #endif -/* return the pid in a pidfile. return 0 if the process (or pidfile) - does not exist */ +/** + * @file + * @brief Pid file handling + */ + +/** + * return the pid in a pidfile. return 0 if the process (or pidfile) + * does not exist + */ pid_t pidfile_pid(const char *name) { int fd; @@ -73,7 +80,9 @@ pid_t pidfile_pid(const char *name) return 0; } -/* create a pid file in the pid directory. open it and leave it locked */ +/** + * create a pid file in the pid directory. open it and leave it locked + */ void pidfile_create(const char *name) { int fd; diff --git a/source/lib/util/signal.c b/source/lib/util/signal.c index 6c0bb4007a1..a0cb90dbf6a 100644 --- a/source/lib/util/signal.c +++ b/source/lib/util/signal.c @@ -22,6 +22,11 @@ #include "includes.h" #include "system/wait.h" +/** + * @file + * @brief Signal handling + */ + /**************************************************************************** Catch child exits and reap the child zombie status. ****************************************************************************/ @@ -61,9 +66,9 @@ static void sig_cld_leave_status(int signum) #endif } -/******************************************************************* +/** Block sigs. -********************************************************************/ +**/ void BlockSignals(BOOL block,int signum) { @@ -88,12 +93,12 @@ void BlockSignals(BOOL block,int signum) #endif } -/******************************************************************* +/** Catch a signal. This should implement the following semantics: 1) The handler remains installed after being called. 2) The signal should be blocked during handler execution. -********************************************************************/ +**/ void (*CatchSignal(int signum,void (*handler)(int )))(int) { @@ -121,18 +126,18 @@ void (*CatchSignal(int signum,void (*handler)(int )))(int) #endif } -/******************************************************************* +/** Ignore SIGCLD via whatever means is necessary for this OS. -********************************************************************/ +**/ void CatchChild(void) { CatchSignal(SIGCLD, sig_cld); } -/******************************************************************* +/** Catch SIGCLD but leave the child around so it's status can be reaped. -********************************************************************/ +**/ void CatchChildLeaveStatus(void) { diff --git a/source/lib/util/substitute.c b/source/lib/util/substitute.c index 34a2ad9f82b..d461cedf4c1 100644 --- a/source/lib/util/substitute.c +++ b/source/lib/util/substitute.c @@ -22,6 +22,11 @@ #include "includes.h" #include "smb_server/smb_server.h" +/** + * @file + * @brief Substitution handling + */ + /* oh bugger - I really didn't want to have a top-level context anywhere, but until we change all lp_*() calls to take a context argument this is needed */ @@ -66,7 +71,7 @@ void sub_set_remote_arch(const char *str) setup_string(&sub->remote_arch, str); } -/* +/** setup the string used by %U substitution */ void sub_set_user_name(const char *name) @@ -75,17 +80,17 @@ void sub_set_user_name(const char *name) setup_string(&sub->user_name, name); } -/**************************************************************************** -FOO -****************************************************************************/ +/** +FIXME +**/ void standard_sub_basic(char *str,size_t len) { } -/**************************************************************************** +/** Do some standard substitutions in a string. This function will return an allocated string that have to be freed. -****************************************************************************/ +**/ char *talloc_sub_basic(TALLOC_CTX *mem_ctx, const char *smb_name, const char *str) { return talloc_strdup(mem_ctx, str); @@ -96,10 +101,10 @@ char *alloc_sub_basic(const char *smb_name, const char *str) return strdup(str); } -/**************************************************************************** +/** Do some specific substitutions in a string. This function will return an allocated string that have to be freed. -****************************************************************************/ +**/ char *talloc_sub_specified(TALLOC_CTX *mem_ctx, const char *input_string, @@ -138,9 +143,9 @@ char *alloc_sub_advanced(int snum, const char *user, return strdup(str); } -/**************************************************************************** +/** Do some standard substitutions in a string. -****************************************************************************/ +**/ void standard_sub_tcon(struct smbsrv_tcon *tcon, char *str, size_t len) { @@ -156,9 +161,9 @@ char *alloc_sub_tcon(struct smbsrv_tcon *tcon, char *str) return strdup(str); } -/**************************************************************************** - Like standard_sub but by snum. -****************************************************************************/ +/** + Like standard_sub but by snum. FIXME +**/ void standard_sub_snum(int snum, char *str, size_t len) { diff --git a/source/lib/util/time.c b/source/lib/util/time.c index 7721a2c456c..a56175cda91 100644 --- a/source/lib/util/time.c +++ b/source/lib/util/time.c @@ -23,6 +23,11 @@ #include "includes.h" #include "system/time.h" +/** + * @file + * @brief time handling functions + */ + #ifndef TIME_T_MIN /* we use 0 here, because (time_t)-1 means error */ #define TIME_T_MIN 0 @@ -37,17 +42,17 @@ #define TIME_T_MAX MIN(INT32_MAX,_TYPE_MAXIMUM(time_t)) #endif -/******************************************************************* +/** External access to time_t_min and time_t_max. -********************************************************************/ +**/ time_t get_time_t_max(void) { return TIME_T_MAX; } -/******************************************************************* +/** a gettimeofday wrapper -********************************************************************/ +**/ void GetTimeOfDay(struct timeval *tval) { #ifdef HAVE_GETTIMEOFDAY_TZ @@ -60,10 +65,10 @@ void GetTimeOfDay(struct timeval *tval) #define TIME_FIXUP_CONSTANT 11644473600LL -/**************************************************************************** +/** interpret an 8 byte "filetime" structure to a time_t It's originally in "100ns units since jan 1st 1601" -****************************************************************************/ +**/ time_t nt_time_to_unix(NTTIME nt) { if (nt == 0) { @@ -84,10 +89,10 @@ time_t nt_time_to_unix(NTTIME nt) } -/**************************************************************************** +/** put a 8 byte filetime from a time_t This takes GMT as input -****************************************************************************/ +**/ void unix_to_nt_time(NTTIME *nt, time_t t) { uint64_t t2; @@ -109,9 +114,9 @@ void unix_to_nt_time(NTTIME *nt, time_t t) } -/**************************************************************************** +/** check if it's a null unix time -****************************************************************************/ +**/ BOOL null_time(time_t t) { return t == 0 || @@ -120,9 +125,9 @@ BOOL null_time(time_t t) } -/**************************************************************************** +/** check if it's a null NTTIME -****************************************************************************/ +**/ BOOL null_nttime(NTTIME t) { return t == 0 || t == (NTTIME)-1; @@ -176,20 +181,20 @@ static uint32_t make_dos_date(time_t unixdate, int zone_offset) return ret; } -/******************************************************************* +/** put a dos date into a buffer (time/date format) This takes GMT time and puts local time in the buffer -********************************************************************/ +**/ void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset) { uint32_t x = make_dos_date(unixdate, zone_offset); SIVAL(buf,offset,x); } -/******************************************************************* +/** put a dos date into a buffer (date/time format) This takes GMT time and puts local time in the buffer -********************************************************************/ +**/ void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset) { uint32_t x; @@ -198,11 +203,11 @@ void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset) SIVAL(buf,offset,x); } -/******************************************************************* +/** put a dos 32 bit "unix like" date into a buffer. This routine takes GMT and converts it to LOCAL time before putting it (most SMBs assume localtime for this sort of date) -********************************************************************/ +**/ void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset) { if (!null_time(unixdate)) { @@ -229,10 +234,10 @@ static void interpret_dos_date(uint32_t date,int *year,int *month,int *day,int * *year = ((p3>>1)&0xFF) + 80; } -/******************************************************************* +/** create a unix date (int GMT) from a dos date (which is actually in localtime) -********************************************************************/ +**/ time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset) { uint32_t dos_date=0; @@ -254,9 +259,9 @@ time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset) return ret; } -/******************************************************************* +/** like make_unix_date() but the words are reversed -********************************************************************/ +**/ time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset) { uint32_t x,x2; @@ -268,10 +273,10 @@ time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset) return pull_dos_date((void *)&x, zone_offset); } -/******************************************************************* +/** create a unix GMT date from a dos date in 32 bit "unix like" format these generally arrive as localtimes, with corresponding DST - ******************************************************************/ +**/ time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset) { time_t t = (time_t)IVAL(date_ptr,0); @@ -282,9 +287,9 @@ time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset) } -/*************************************************************************** +/** return a HTTP/1.0 time string - ***************************************************************************/ +**/ char *http_timestring(TALLOC_CTX *mem_ctx, time_t t) { char *buf; @@ -308,9 +313,9 @@ char *http_timestring(TALLOC_CTX *mem_ctx, time_t t) return buf; } -/**************************************************************************** +/** Return the date and time as a string -****************************************************************************/ +**/ char *timestring(TALLOC_CTX *mem_ctx, time_t t) { char *TimeBuf; @@ -338,7 +343,7 @@ char *timestring(TALLOC_CTX *mem_ctx, time_t t) return TimeBuf; } -/* +/** return a talloced string representing a NTTIME for human consumption */ const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt) @@ -352,7 +357,7 @@ const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt) } -/* +/** put a NTTIME into a packet */ void push_nttime(uint8_t *base, uint16_t offset, NTTIME t) @@ -360,7 +365,7 @@ void push_nttime(uint8_t *base, uint16_t offset, NTTIME t) SBVAL(base, offset, t); } -/* +/** pull a NTTIME from a packet */ NTTIME pull_nttime(uint8_t *base, uint16_t offset) @@ -369,7 +374,7 @@ NTTIME pull_nttime(uint8_t *base, uint16_t offset) return ret; } -/* +/** parse a nttime as a large integer in a string and return a NTTIME */ NTTIME nttime_from_string(const char *s) @@ -377,7 +382,7 @@ NTTIME nttime_from_string(const char *s) return strtoull(s, NULL, 0); } -/* +/** return (tv1 - tv2) in microseconds */ int64_t usec_time_diff(struct timeval *tv1, struct timeval *tv2) @@ -387,7 +392,7 @@ int64_t usec_time_diff(struct timeval *tv1, struct timeval *tv2) } -/* +/** return a zero timeval */ struct timeval timeval_zero(void) @@ -398,7 +403,7 @@ struct timeval timeval_zero(void) return tv; } -/* +/** return True if a timeval is zero */ BOOL timeval_is_zero(const struct timeval *tv) @@ -406,7 +411,7 @@ BOOL timeval_is_zero(const struct timeval *tv) return tv->tv_sec == 0 && tv->tv_usec == 0; } -/* +/** return a timeval for the current time */ struct timeval timeval_current(void) @@ -416,7 +421,7 @@ struct timeval timeval_current(void) return tv; } -/* +/** return a timeval struct with the given elements */ struct timeval timeval_set(uint32_t secs, uint32_t usecs) @@ -428,7 +433,7 @@ struct timeval timeval_set(uint32_t secs, uint32_t usecs) } -/* +/** return a timeval ofs microseconds after tv */ struct timeval timeval_add(const struct timeval *tv, @@ -443,7 +448,7 @@ struct timeval timeval_add(const struct timeval *tv, return tv2; } -/* +/** return the sum of two timeval structures */ struct timeval timeval_sum(const struct timeval *tv1, @@ -452,7 +457,7 @@ struct timeval timeval_sum(const struct timeval *tv1, return timeval_add(tv1, tv2->tv_sec, tv2->tv_usec); } -/* +/** return a timeval secs/usecs into the future */ struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs) @@ -461,7 +466,7 @@ struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs) return timeval_add(&tv, secs, usecs); } -/* +/** compare two timeval structures. Return -1 if tv1 < tv2 Return 0 if tv1 == tv2 @@ -476,7 +481,7 @@ int timeval_compare(const struct timeval *tv1, const struct timeval *tv2) return 0; } -/* +/** return True if a timer is in the past */ BOOL timeval_expired(const struct timeval *tv) @@ -487,7 +492,7 @@ BOOL timeval_expired(const struct timeval *tv) return (tv2.tv_usec >= tv->tv_usec); } -/* +/** return the number of seconds elapsed between two times */ double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2) @@ -496,7 +501,7 @@ double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2) (tv2->tv_usec - tv1->tv_usec)*1.0e-6; } -/* +/** return the number of seconds elapsed since a given time */ double timeval_elapsed(const struct timeval *tv) @@ -505,7 +510,7 @@ double timeval_elapsed(const struct timeval *tv) return timeval_elapsed2(tv, &tv2); } -/* +/** return the lesser of two timevals */ struct timeval timeval_min(const struct timeval *tv1, @@ -517,7 +522,7 @@ struct timeval timeval_min(const struct timeval *tv1, return *tv2; } -/* +/** return the greater of two timevals */ struct timeval timeval_max(const struct timeval *tv1, @@ -529,7 +534,7 @@ struct timeval timeval_max(const struct timeval *tv1, return *tv2; } -/* +/** return the difference between two timevals as a timeval if tv1 comes after tv2, then return a zero timeval (this is *tv2 - *tv1) @@ -552,7 +557,7 @@ struct timeval timeval_until(const struct timeval *tv1, } -/* +/** convert a timeval to a NTTIME */ NTTIME timeval_to_nttime(const struct timeval *tv) @@ -579,9 +584,9 @@ static int tm_diff(struct tm *a, struct tm *b) return seconds; } -/******************************************************************* +/** return the UTC offset in seconds west of UTC, or 0 if it cannot be determined - ******************************************************************/ + */ int get_time_zone(time_t t) { struct tm *tm = gmtime(&t); diff --git a/source/lib/util/unix_privs.c b/source/lib/util/unix_privs.c index 3c0f3197767..13b0aa203c7 100644 --- a/source/lib/util/unix_privs.c +++ b/source/lib/util/unix_privs.c @@ -23,6 +23,11 @@ #include "includes.h" #include "system/filesys.h" +/** + * @file + * @brief Gaining/losing root privileges + */ + /* there are times when smbd needs to temporarily gain root privileges to do some operation. To do this you call root_privileges(), which diff --git a/source/lib/util/util.c b/source/lib/util/util.c index 17dde332e1a..074dc000fb7 100644 --- a/source/lib/util/util.c +++ b/source/lib/util/util.c @@ -28,10 +28,15 @@ #include "system/iconv.h" #include "system/filesys.h" -/*************************************************************************** +/** + * @file + * @brief Misc utility functions + */ + +/** Find a suitable temporary directory. The result should be copied immediately as it may be overwritten by a subsequent call. -****************************************************************************/ +**/ const char *tmpdir(void) { char *p; @@ -41,9 +46,9 @@ const char *tmpdir(void) } -/******************************************************************* +/** Check if a file exists - call vfs_file_exist for samba files. -********************************************************************/ +**/ BOOL file_exist(const char *fname) { struct stat st; @@ -55,9 +60,9 @@ BOOL file_exist(const char *fname) return ((S_ISREG(st.st_mode)) || (S_ISFIFO(st.st_mode))); } -/******************************************************************* +/** Check a files mod time. -********************************************************************/ +**/ time_t file_modtime(const char *fname) { @@ -69,9 +74,9 @@ time_t file_modtime(const char *fname) return(st.st_mtime); } -/******************************************************************* +/** Check if a directory exists. -********************************************************************/ +**/ BOOL directory_exist(const char *dname) { @@ -167,12 +172,12 @@ static void close_low_fds(BOOL stderr_too) #endif } -/**************************************************************************** +/** Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available, else if SYSV use O_NDELAY if BSD use FNDELAY -****************************************************************************/ +**/ int set_blocking(int fd, BOOL set) { @@ -198,9 +203,9 @@ int set_blocking(int fd, BOOL set) } -/******************************************************************* +/** Sleep for a specified number of milliseconds. -********************************************************************/ +**/ void msleep(uint_t t) { @@ -213,9 +218,9 @@ void msleep(uint_t t) select(0,NULL,NULL,NULL,&tval); } -/**************************************************************************** +/** Become a daemon, discarding the controlling terminal. -****************************************************************************/ +**/ void become_daemon(BOOL Fork) { @@ -244,11 +249,11 @@ void become_daemon(BOOL Fork) } -/**************************************************************************** +/** Free memory, checks for NULL. Use directly SAFE_FREE() Exists only because we need to pass a function pointer somewhere --SSS -****************************************************************************/ +**/ void safe_free(void *p) { @@ -256,7 +261,7 @@ void safe_free(void *p) } -/* +/** see if a string matches either our primary or one of our secondary netbios aliases. do a case insensitive match */ @@ -280,9 +285,9 @@ BOOL is_myname(const char *name) } -/**************************************************************************** +/** Get my own name, return in malloc'ed storage. -****************************************************************************/ +**/ char* get_myname(void) { @@ -311,9 +316,9 @@ char* get_myname(void) return hostname; } -/**************************************************************************** +/** Return true if a string could be a pure IP address. -****************************************************************************/ +**/ BOOL is_ipaddress(const char *str) { @@ -330,9 +335,9 @@ BOOL is_ipaddress(const char *str) return pure_address; } -/**************************************************************************** +/** Interpret an internet address or name into an IP address in 4 byte form. -****************************************************************************/ +**/ uint32_t interpret_addr(const char *str) { struct hostent *hp; @@ -375,9 +380,9 @@ uint32_t interpret_addr(const char *str) return(res); } -/******************************************************************* +/** A convenient addition to interpret_addr(). -******************************************************************/ +**/ struct ipv4_addr interpret_addr2(const char *str) { struct ipv4_addr ret; @@ -386,18 +391,18 @@ struct ipv4_addr interpret_addr2(const char *str) return ret; } -/******************************************************************* +/** Check if an IP is the 0.0.0.0. -******************************************************************/ +**/ BOOL is_zero_ip(struct ipv4_addr ip) { return ip.addr == 0; } -/******************************************************************* +/** Are two IPs on the same subnet? -********************************************************************/ +**/ BOOL same_net(struct ipv4_addr ip1,struct ipv4_addr ip2,struct ipv4_addr mask) { @@ -411,9 +416,9 @@ BOOL same_net(struct ipv4_addr ip1,struct ipv4_addr ip2,struct ipv4_addr mask) } -/**************************************************************************** +/** Check if a process exists. Does this work on all unixes? -****************************************************************************/ +**/ BOOL process_exists(pid_t pid) { @@ -423,10 +428,10 @@ BOOL process_exists(pid_t pid) return(kill(pid,0) == 0 || errno != ESRCH); } -/**************************************************************************** +/** Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping is dealt with in posix.c -****************************************************************************/ +**/ BOOL fcntl_lock(int fd, int op, off_t offset, off_t count, int type) { @@ -513,9 +518,9 @@ void dump_data(int level, const uint8_t *buf,int len) } } -/***************************************************************** +/** malloc that aborts with smb_panic on fail or zero size. - *****************************************************************/ +**/ void *smb_xmalloc(size_t size) { @@ -552,9 +557,9 @@ char *smb_xstrdup(const char *s) } -/***************************************************************** +/** Like strdup but for memory. -*****************************************************************/ +**/ void *memdup(const void *p, size_t size) { @@ -568,9 +573,9 @@ void *memdup(const void *p, size_t size) return p2; } -/***************************************************************** +/** A useful function for returning a path in the Samba lock directory. -*****************************************************************/ +**/ char *lock_path(TALLOC_CTX* mem_ctx, const char *name) { char *fname, *dname; @@ -596,9 +601,9 @@ char *lock_path(TALLOC_CTX* mem_ctx, const char *name) } -/***************************************************************** +/** A useful function for returning a path in the Samba piddir directory. -*****************************************************************/ +**/ static char *pid_path(TALLOC_CTX* mem_ctx, const char *name) { char *fname, *dname; @@ -654,7 +659,7 @@ char *private_path(TALLOC_CTX* mem_ctx, const char *name) return fname; } -/* +/** return a path in the smbd.tmp directory, where all temporary file for smbd go. If NULL is passed for name then return the directory path itself @@ -707,8 +712,10 @@ void dump_data_pw(const char *msg, const uint8_t * data, size_t len) } -/* see if a range of memory is all zero. A NULL pointer is considered - to be all zero */ +/** + * see if a range of memory is all zero. A NULL pointer is considered + * to be all zero + */ BOOL all_zero(const uint8_t *ptr, uint_t size) { int i; @@ -719,7 +726,7 @@ BOOL all_zero(const uint8_t *ptr, uint_t size) return True; } -/* +/** realloc an array, checking for integer overflow in the array size */ void *realloc_array(void *ptr, size_t el_size, unsigned count) diff --git a/source/lib/util/util_file.c b/source/lib/util/util_file.c index 246b03b4aa4..5e55b818731 100644 --- a/source/lib/util/util_file.c +++ b/source/lib/util/util_file.c @@ -24,11 +24,16 @@ #include "system/shmem.h" #include "system/filesys.h" -/**************************************************************************** +/** + * @file + * @brief File-related utility functions + */ + +/** read a line from a file with possible \ continuation chars. Blanks at the start or end of a line are stripped. The string will be allocated if s2 is NULL -****************************************************************************/ +**/ char *fgets_slash(char *s2,int maxlen,XFILE *f) { char *s=s2; @@ -98,7 +103,9 @@ char *fgets_slash(char *s2,int maxlen,XFILE *f) return(s); } -/* Read one line (data until next newline or eof) and allocate it */ +/** + * Read one line (data until next newline or eof) and allocate it + */ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint) { char *data = NULL; @@ -146,9 +153,9 @@ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint) } -/**************************************************************************** +/** load a file into memory from a fd. -****************************************************************************/ +**/ char *fd_load(int fd, size_t *size, TALLOC_CTX *mem_ctx) { @@ -171,9 +178,9 @@ char *fd_load(int fd, size_t *size, TALLOC_CTX *mem_ctx) return p; } -/**************************************************************************** +/** load a file into memory -****************************************************************************/ +**/ char *file_load(const char *fname, size_t *size, TALLOC_CTX *mem_ctx) { int fd; @@ -192,9 +199,9 @@ char *file_load(const char *fname, size_t *size, TALLOC_CTX *mem_ctx) } -/******************************************************************* +/** mmap (if possible) or read a file -********************************************************************/ +**/ void *map_file(const char *fname, size_t size) { size_t s2 = 0; @@ -228,9 +235,9 @@ void *map_file(const char *fname, size_t size) } -/**************************************************************************** +/** parse a buffer into lines -****************************************************************************/ +**/ static char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx) { int i; @@ -267,10 +274,10 @@ static char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX * } -/**************************************************************************** +/** load a file into memory and return an array of pointers to lines in the file must be freed with talloc_free(). -****************************************************************************/ +**/ char **file_lines_load(const char *fname, int *numlines, TALLOC_CTX *mem_ctx) { char *p; @@ -287,11 +294,11 @@ char **file_lines_load(const char *fname, int *numlines, TALLOC_CTX *mem_ctx) return lines; } -/**************************************************************************** +/** load a fd into memory and return an array of pointers to lines in the file must be freed with talloc_free(). If convert is true calls unix_to_dos on the list. -****************************************************************************/ +**/ char **fd_lines_load(int fd, int *numlines, TALLOC_CTX *mem_ctx) { char *p; @@ -309,10 +316,10 @@ char **fd_lines_load(int fd, int *numlines, TALLOC_CTX *mem_ctx) } -/**************************************************************************** +/** take a list of lines and modify them to produce a list where \ continues a line -****************************************************************************/ +**/ void file_lines_slashcont(char **lines) { int i, j; @@ -332,7 +339,7 @@ void file_lines_slashcont(char **lines) } } -/* +/** save a lump of data into a file. Mostly used for debugging */ BOOL file_save(const char *fname, const void *packet, size_t length) @@ -349,7 +356,7 @@ BOOL file_save(const char *fname, const void *packet, size_t length) return True; } -/* +/** see if a file exists */ BOOL file_exists(const char *path) diff --git a/source/lib/util/util_sock.c b/source/lib/util/util_sock.c index 8a65a27d020..e3913f56a99 100644 --- a/source/lib/util/util_sock.c +++ b/source/lib/util/util_sock.c @@ -22,6 +22,11 @@ #include "includes.h" #include "system/network.h" +/** + * @file + * @brief Socket utility functions + */ + enum SOCK_OPT_TYPES {OPT_BOOL,OPT_INT,OPT_ON}; static const struct { @@ -67,9 +72,9 @@ static const struct { {NULL,0,0,0,0}}; -/**************************************************************************** +/** Set user socket options. -****************************************************************************/ +**/ void set_socket_options(int fd, const char *options) { const char **options_list = str_list_make(NULL, options, " \t,"); diff --git a/source/lib/util/util_str.c b/source/lib/util/util_str.c index b46787e3ea2..11a95731deb 100644 --- a/source/lib/util/util_str.c +++ b/source/lib/util/util_str.c @@ -983,10 +983,10 @@ size_t valgrind_strlen(const char *s) #endif -/* +/** format a string into length-prefixed dotted domain format, as used in NBT and in some ADS structures -*/ +**/ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s) { char *ret; @@ -1036,9 +1036,9 @@ BOOL add_string_to_array(TALLOC_CTX *mem_ctx, -/* +/** varient of strcmp() that handles NULL ptrs -*/ +**/ int strcmp_safe(const char *s1, const char *s2) { if (s1 == s2) { @@ -1051,11 +1051,11 @@ int strcmp_safe(const char *s1, const char *s2) } -/******************************************************************* +/** return the number of bytes occupied by a buffer in ASCII format the result includes the null termination limited by 'n' bytes -********************************************************************/ +**/ size_t ascii_len_n(const char *src, size_t n) { size_t len; @@ -1069,9 +1069,9 @@ size_t ascii_len_n(const char *src, size_t n) } -/******************************************************************* +/** Return a string representing a CIFS attribute for a file. -********************************************************************/ +**/ char *attrib_string(TALLOC_CTX *mem_ctx, uint32_t attrib) { int i, len; @@ -1113,11 +1113,11 @@ char *attrib_string(TALLOC_CTX *mem_ctx, uint32_t attrib) return ret; } -/*************************************************************************** +/** Set a boolean variable from the text value stored in the passed string. Returns True in success, False if the passed string does not correctly represent a boolean. -***************************************************************************/ +**/ BOOL set_boolean(const char *boolean_string, BOOL *boolean) { @@ -1155,7 +1155,9 @@ BOOL conv_str_bool(const char * str, BOOL * val) return True; } -/* Convert a size specification like 16K into an integral number of bytes. */ +/** + * Convert a size specification like 16K into an integral number of bytes. + **/ BOOL conv_str_size(const char * str, uint64_t * val) { char * end = NULL; diff --git a/source/lib/util/util_strlist.c b/source/lib/util/util_strlist.c index ec6c58162f7..e3d51260292 100644 --- a/source/lib/util/util_strlist.c +++ b/source/lib/util/util_strlist.c @@ -21,7 +21,12 @@ #include "includes.h" -/* +/** + * @file + * @brief String list manipulation + */ + +/** build a null terminated list of strings from a input string and a separator list. The separator list must contain characters less than or equal to 0x2f for this to work correctly on multi-byte strings @@ -71,9 +76,10 @@ const char **str_list_make(TALLOC_CTX *mem_ctx, const char *string, const char * return ret; } -/* build a null terminated list of strings from an argv-like input string - Entries are seperated by spaces and can be enclosed by quotes. - Does NOT support escaping +/** + * build a null terminated list of strings from an argv-like input string + * Entries are seperated by spaces and can be enclosed by quotes. + * Does NOT support escaping */ const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep) { @@ -131,7 +137,9 @@ const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const } -/* join a list back to one string */ +/** + * join a list back to one string + */ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator) { char *ret = NULL; @@ -149,7 +157,7 @@ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator) return ret; } -/* join a list back to one (shell-like) string; entries +/** join a list back to one (shell-like) string; entries * seperated by spaces, using quotes where necessary */ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep) { @@ -174,7 +182,7 @@ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep) return ret; } -/* +/** return the number of elements in a string list */ size_t str_list_length(const char **list) @@ -185,7 +193,7 @@ size_t str_list_length(const char **list) } -/* +/** copy a string list */ const char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list) @@ -205,7 +213,7 @@ const char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list) return ret; } -/* +/** Return true if all the elements of the list match exactly. */ BOOL str_list_equal(const char **list1, const char **list2) @@ -228,7 +236,7 @@ BOOL str_list_equal(const char **list1, const char **list2) } -/* +/** add an entry to a string list */ const char **str_list_add(const char **list, const char *s) @@ -247,7 +255,7 @@ const char **str_list_add(const char **list, const char *s) return ret; } -/* +/** remove an entry from a string list */ void str_list_remove(const char **list, const char *s) @@ -265,7 +273,7 @@ void str_list_remove(const char **list, const char *s) } -/* +/** return True if a string is in a list */ BOOL str_list_check(const char **list, const char *s) @@ -278,7 +286,7 @@ BOOL str_list_check(const char **list, const char *s) return False; } -/* +/** return True if a string is in a list, case insensitively */ BOOL str_list_check_ci(const char **list, const char *s) diff --git a/source/lib/util/util_unistr.c b/source/lib/util/util_unistr.c index b35822877cc..81aa0d67525 100644 --- a/source/lib/util/util_unistr.c +++ b/source/lib/util/util_unistr.c @@ -22,6 +22,11 @@ #include "includes.h" #include "system/iconv.h" +/** + * @file + * @brief Unicode string manipulation + */ + /* these 2 tables define the unicode case handling. They are loaded at startup either via mmap() or read() from the lib directory */ static void *upcase_table; @@ -58,9 +63,9 @@ static void load_case_tables(void) } } -/******************************************************************* +/** Convert a codepoint_t to upper case. -********************************************************************/ +**/ codepoint_t toupper_w(codepoint_t val) { if (val < 128) { @@ -78,9 +83,9 @@ codepoint_t toupper_w(codepoint_t val) return SVAL(upcase_table, val*2); } -/******************************************************************* +/** Convert a codepoint_t to lower case. -********************************************************************/ +**/ codepoint_t tolower_w(codepoint_t val) { if (val < 128) { @@ -98,10 +103,10 @@ codepoint_t tolower_w(codepoint_t val) return SVAL(lowcase_table, val*2); } -/******************************************************************* +/** return the number of bytes occupied by a buffer in CH_UTF16 format the result includes the null termination -********************************************************************/ +**/ size_t utf16_len(const void *buf) { size_t len; @@ -111,11 +116,11 @@ size_t utf16_len(const void *buf) return len + 2; } -/******************************************************************* +/** return the number of bytes occupied by a buffer in CH_UTF16 format the result includes the null termination limited by 'n' bytes -********************************************************************/ +**/ size_t utf16_len_n(const void *src, size_t n) { size_t len; @@ -137,7 +142,7 @@ size_t ucs2_align(const void *base_ptr, const void *p, int flags) return PTR_DIFF(p, base_ptr) & 1; } -/* +/** compare two codepoints case insensitively */ int codepoint_cmpi(codepoint_t c1, codepoint_t c2) diff --git a/source/lib/util/xfile.c b/source/lib/util/xfile.c index 794e3f0f5e8..43f0f85f52d 100644 --- a/source/lib/util/xfile.c +++ b/source/lib/util/xfile.c @@ -18,6 +18,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/** + * @file + * @brief scalable FILE replacement + */ + /* stdio is very convenient, but on some systems the file descriptor in FILE* is 8 bits, so it fails when more than 255 files are open.