From 2fb91e19a02ff8a3e43145d582cfebaf3a60f1d9 Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Sat, 5 Oct 2013 16:10:30 -0400 Subject: Sanitize the registered function interface. Expand the characters which are legal in a function name, and check the name for validity. Create a type for the function pointer. Convert the last argument from a boolean to flags, to allow for expansion. --- doc/make.texi | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/make.texi b/doc/make.texi index 42cec7f..8fbdb61 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -11115,16 +11115,14 @@ arguments are as follows: @table @code @item name The function name. This is what the makefile should use to invoke the -function. The name must be between 1 and 255 characters long. +function. The name must be between 1 and 255 characters long and it +may only contain alphanumeric, period (@samp{.}), dash (@samp{-}), and +underscore (@samp{_}) characters. It may not begin with a period. @item func_ptr A pointer to a function that @code{make} will invoke when it expands the function in a makefile. This function must be defined by the -loaded object. GNU @code{make} will call it with three arguments: -@code{name} (the same name as above), @code{argc} (the number of -arguments to the function), and @code{argv} (the list of arguments to -the function). The last argument (that is, @code{argv[argc]} will be -null (@code{0}). +loaded object. @item min_args The minimum number of arguments the function will accept. Must be @@ -11140,12 +11138,30 @@ arguments. If the value is 0, then any number of arguments is accepted. If the value is greater than 0, then it must be greater than or equal to @code{min_args}. -@item expand_args -If this value is 0, then @code{make} will not expand the arguments to -the function before passing them to @code{func_ptr}. If the value is -non-0, then the arguments will be expanded first. +@item flags +Flags that specify how this function will operate; the desired flags +should be OR'd together. If the @code{GMK_FUNC_NOEXPAND} flag is +given then the function arguments will not be expanded before the +function is called; otherwise they will be expanded first. @end table +@subsubheading Registered Function Interface +@findex gmk_func_ptr + +A function registered with @code{make} must match the +@code{gmk_func_ptr} type. It will be invoked with three parameters: +@code{name} (the name of the function), @code{argc} (the number of +arguments to the function), and @code{argv} (an array of pointers to +arguments to the function). The last pointer (that is, +@code{argv[argc]}) will be null (@code{0}). + +The return value of the function is the result of expanding the +function. If the function expands to nothing the return value may be +null. Otherwise, it must be a pointer to a string created with +@code{gmk_alloc}. Once the function returns, @code{make} owns this +string and will free it when appropriate; it cannot be accessed by the +loaded object. + @subsubheading GNU @code{make} Facilities There are some facilities exported by GNU @code{make} for use by @@ -11184,6 +11200,12 @@ should never pass memory that you've allocated directly to any memory returned to you by any @code{make} function. Instead, use the @code{gmk_alloc} and @code{gmk_free} functions. +In particular, the string returned to @code{make} by a function +registered using @code{gmk_add_function} @emph{must} be allocated +using @code{gmk_alloc}, and the string returned from the @code{make} +@code{gmk_expand} function @emph{must} be freed (when no longer +needed) using @code{gmk_free}. + @table @code @item gmk_alloc @findex gmk_alloc -- cgit v1.2.3