X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=libiberty%2Ffunctions.texi;h=fd3e8e74ea7b17565dfa00aadf3726071c6f9c2c;hb=36fc76aebb7315571094d66b35e13d69d512fbe2;hp=ac97726805ae4587e0baa3597910e7c795527f80;hpb=c631edf1cc79aa305924c762642b9160cae94e2d;p=deliverable%2Fbinutils-gdb.git diff --git a/libiberty/functions.texi b/libiberty/functions.texi index ac97726805..fd3e8e74ea 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -25,139 +25,6 @@ nineteen EBCDIC varying characters is tested; exercise caution.) @end ftable @end defvr -@c pexecute.txh:1 -@deftypefn Extension struct pex_obj *pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) - -Prepare to execute one or more programs, with standard output of each -program fed to standard input of the next. This is a system -independent interface to execute a pipeline. - -@var{flags} is a bitwise combination of the following: - -@table @code - -@vindex PEX_RECORD_TIMES -@item PEX_RECORD_TIMES -Record subprocess times if possible. - -@vindex PEX_USE_PIPES -@item PEX_USE_PIPES -Use pipes for communication between processes, if possible. - -@vindex PEX_SAVE_TEMPS -@item PEX_SAVE_TEMPS -Don't delete temporary files used for communication between -processes. - -@end table - -@var{pname} is the name of program to be executed, used in error -messages. @var{tempbase} is a base name to use for any required -temporary files; it may be @code{NULL} to use a randomly chosen name. - -@end deftypefn - -@c pexecute.txh:161 -@deftypefn Extension const char *pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err}) - -An interface to @code{pex_init} to permit the easy execution of a -single program. The return value and most of the parameters are as -for a call to @code{pex_run}. @var{flags} is restricted to a -combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and -@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if -@code{PEX_LAST} were set. On a successful return, *@var{status} will -be set to the exit status of the program. - -@end deftypefn - -@c pexecute.txh:32 -@deftypefn Extension const char *pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) - -Execute one program in a pipeline. On success this returns -@code{NULL}. On failure it returns an error message, a statically -allocated string. - -@var{obj} is returned by a previous call to @code{pex_init}. - -@var{flags} is a bitwise combination of the following: - -@table @code - -@vindex PEX_LAST -@item PEX_LAST -This must be set on the last program in the pipeline. In particular, -it should be set when executing a single program. The standard output -of the program will be sent to @var{outname}, or, if @var{outname} is -@code{NULL}, to the standard output of the calling program. This -should not be set if you want to call @code{pex_read_output} -(described below). After a call to @code{pex_run} with this bit set, -@var{pex_run} may no longer be called with the same @var{obj}. - -@vindex PEX_SEARCH -@item PEX_SEARCH -Search for the program using the user's executable search path. - -@vindex PEX_SUFFIX -@item PEX_SUFFIX -@var{outname} is a suffix. See the description of @var{outname}, -below. - -@vindex PEX_STDERR_TO_STDOUT -@item PEX_STDERR_TO_STDOUT -Send the program's standard error to standard output, if possible. - -@vindex PEX_BINARY_INPUT -@vindex PEX_BINARY_OUTPUT -@item PEX_BINARY_INPUT -@itemx PEX_BINARY_OUTPUT -The standard input (output) of the program should be read (written) in -binary mode rather than text mode. These flags are ignored on systems -which do not distinguish binary mode and text mode, such as Unix. For -proper behavior these flags should match appropriately--a call to -@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a -call using @code{PEX_BINARY_INPUT}. -@end table - -@var{executable} is the program to execute. @var{argv} is the set of -arguments to pass to the program; normally @code{@var{argv}[0]} will -be a copy of @var{executable}. - -@var{outname} is used to set the name of the file to use for standard -output. There are two cases in which no output file will be used: 1) -if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} -was set in the call to @code{pex_init}, and the system supports pipes; -2) if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is -@code{NULL}. Otherwise the code will use a file to hold standard -output. If @code{PEX_LAST} is not set, this file is considered to be -a temporary file, and it will be removed when no longer needed, unless -@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. - -There are two cases to consider when setting the name of the file to -hold standard output. - -First case: @code{PEX_SUFFIX} is set in @var{flags}. In this case -@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter -to @code{pex_init} was not @code{NULL}, then the output file name is -the concatenation of @var{tempbase} and @var{outname}. If -@var{tempbase} was @code{NULL}, then the output file name is a random -file name ending in @var{outname}. - -Second case: @code{PEX_SUFFIX} was not set in @var{flags}. In this -case, if @var{outname} is not @code{NULL}, it is used as the output -file name. If @var{outname} is @code{NULL}, and @var{tempbase} was -not NULL, the output file name is randomly chosen using -@var{tempbase}. Otherwise the output file name is chosen completely -at random. - -@var{errname} is the file name to use for standard error output. If -it is @code{NULL}, standard error is the same as the caller. -Otherwise, standard error is written to the named file. - -On an error return, the code sets @code{*@var{err}} to an @code{errno} -value, or to 0 if there is no relevant @code{errno}. - -@end deftypefn - @c alloca.c:26 @deftypefn Replacement void* alloca (size_t @var{size}) @@ -286,7 +153,7 @@ find one. The current directory is chosen if all else fails so the program is exited if a temporary directory can't be found (@code{mktemp} fails). The buffer for the result is obtained with @code{xmalloc}. -This function is provided for backwards compatability only. Its use is +This function is provided for backwards compatibility only. Its use is not recommended. @end deftypefn @@ -347,6 +214,26 @@ symbolic name or message. @end deftypefn +@c argv.c:293 +@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) + +The @var{argcp} and @code{argvp} arguments are pointers to the usual +@code{argc} and @code{argv} arguments to @code{main}. This function +looks for arguments that begin with the character @samp{@@}. Any such +arguments are interpreted as ``response files''. The contents of the +response file are interpreted as additional command line options. In +particular, the file is separated into whitespace-separated strings; +each such string is taken as a command-line option. The new options +are inserted in place of the option naming the response file, and +@code{*argcp} and @code{*argvp} will be updated. If the value of +@code{*argvp} is modified by this function, then the new value has +been dynamically allocated and can be deallocated by the caller with +@code{freeargv}. However, most callers will simply call +@code{expandargv} near the beginning of @code{main} and allow the +operating system to free the memory when the program exits. + +@end deftypefn + @c fdmatch.c:23 @deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) @@ -363,7 +250,7 @@ and inode numbers. @end deftypefn @c fopen_unlocked.c:48 -@deftypefn Extension FILE * fdopen_unlocked (int @var{fildes}, const char * @var{mode}) +@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode}) Opens and returns a @code{FILE} pointer via @code{fdopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -381,6 +268,22 @@ value 1). If @var{valu} is zero, zero is returned. @end deftypefn +@c filename_cmp.c:28 +@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) + +Return zero if the two paths @var{s1} and @var{s2} are equivalent. +If not equivalent, the returned value is similar to what strcmp would +return. In other words, it returns a negative value if @var{s1} is less +than @var{s2}, or a positive value if @var{s2} is greater than @var{s2}. + +This function does not normalize path names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + @c fnmatch.txh:1 @deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags}) @@ -432,7 +335,7 @@ Ignores case when performing the comparison. @end deftypefn @c fopen_unlocked.c:39 -@deftypefn Extension FILE * fopen_unlocked (const char *@var{path}, const char * @var{mode}) +@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode}) Opens and returns a @code{FILE} pointer via @code{fopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -452,7 +355,7 @@ itself. @end deftypefn @c fopen_unlocked.c:57 -@deftypefn Extension FILE * freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream}) +@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream}) Opens and returns a @code{FILE} pointer via @code{freopen}. If the operating system supports it, ensure that the stream is setup to avoid @@ -533,7 +436,7 @@ or zero if it is not. Note that the value you pass will be cast to @deftypefn Extension {unsigned int} hex_value (int @var{c}) Returns the numeric equivalent of the given character when interpreted -as a hexidecimal digit. The result is undefined if you pass an +as a hexadecimal digit. The result is undefined if you pass an invalid hex digit. Note that the value you pass will be cast to @code{unsigned char} within the macro. @@ -763,32 +666,32 @@ Sets the first @var{count} bytes of @var{s} to the constant byte @end deftypefn -@c mkstemps.c:54 -@deftypefn Replacement int mkstemps (char *@var{template}, int @var{suffix_len}) +@c mkstemps.c:58 +@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) -Generate a unique temporary file name from @var{template}. -@var{template} has the form: +Generate a unique temporary file name from @var{pattern}. +@var{pattern} has the form: @example @var{path}/ccXXXXXX@var{suffix} @end example @var{suffix_len} tells us how long @var{suffix} is (it can be zero -length). The last six characters of @var{template} before @var{suffix} +length). The last six characters of @var{pattern} before @var{suffix} must be @samp{XXXXXX}; they are replaced with a string that makes the filename unique. Returns a file descriptor open on the file for reading and writing. @end deftypefn -@c pexecute.txh:155 +@c pexecute.txh:266 @deftypefn Extension void pex_free (struct pex_obj @var{obj}) Clean up and free all data associated with @var{obj}. @end deftypefn -@c pexecute.txh:131 +@c pexecute.txh:241 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) Returns the exit status of all programs run using @var{obj}. @@ -798,7 +701,7 @@ to @code{pex_run}. Returns 0 on error, 1 on success. @end deftypefn -@c pexecute.txh:140 +@c pexecute.txh:250 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) Returns the process execution times of all programs run using @@ -807,15 +710,137 @@ results will be placed into @var{vector}. The results are in the order of the calls to @code{pex_run}. Returns 0 on error, 1 on success. -@code{struct pex_time} has the following fields: @code{user_seconds}, +@code{struct pex_time} has the following fields of the type +@code{unsigned long}: @code{user_seconds}, @code{user_microseconds}, @code{system_seconds}, @code{system_microseconds}. On systems which do not support reporting process times, all the fields will be set to @code{0}. @end deftypefn -@c pexecute.txh:119 -@deftypefn Extension FILE * pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) +@c pexecute.txh:2 +@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) + +Prepare to execute one or more programs, with standard output of each +program fed to standard input of the next. This is a system +independent interface to execute a pipeline. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_RECORD_TIMES +@item PEX_RECORD_TIMES +Record subprocess times if possible. + +@vindex PEX_USE_PIPES +@item PEX_USE_PIPES +Use pipes for communication between processes, if possible. + +@vindex PEX_SAVE_TEMPS +@item PEX_SAVE_TEMPS +Don't delete temporary files used for communication between +processes. + +@end table + +@var{pname} is the name of program to be executed, used in error +messages. @var{tempbase} is a base name to use for any required +temporary files; it may be @code{NULL} to use a randomly chosen name. + +@end deftypefn + +@c pexecute.txh:155 +@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name}) + +Return a stream for a temporary file to pass to the first program in +the pipeline as input. + +The name of the input file is chosen according to the same rules +@code{pex_run} uses to choose output file names, based on +@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. + +Don't call @code{fclose} on the returned stream; the first call to +@code{pex_run} closes it automatically. + +If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in +binary mode; otherwise, open it in the default mode. Including +@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. +@end deftypefn + +@c pexecute.txh:172 +@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary}) + +Return a stream @var{fp} for a pipe connected to the standard input of +the first program in the pipeline; @var{fp} is opened for writing. +You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call +that returned @var{obj}. + +You must close @var{fp} using @code{fclose} yourself when you have +finished writing data to the pipeline. + +The file descriptor underlying @var{fp} is marked not to be inherited +by child processes. + +On systems that do not support pipes, this function returns +@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would +like to write code that is portable to all systems the @code{pex} +functions support, consider using @code{pex_input_file} instead. + +There are two opportunities for deadlock using +@code{pex_input_pipe}: + +@itemize @bullet +@item +Most systems' pipes can buffer only a fixed amount of data; a process +that writes to a full pipe blocks. Thus, if you write to @file{fp} +before starting the first process, you run the risk of blocking when +there is no child process yet to read the data and allow you to +continue. @code{pex_input_pipe} makes no promises about the +size of the pipe's buffer, so if you need to write any data at all +before starting the first process in the pipeline, consider using +@code{pex_input_file} instead. + +@item +Using @code{pex_input_pipe} and @code{pex_read_output} together +may also cause deadlock. If the output pipe fills up, so that each +program in the pipeline is waiting for the next to read more data, and +you fill the input pipe by writing more data to @var{fp}, then there +is no way to make progress: the only process that could read data from +the output pipe is you, but you are blocked on the input pipe. + +@end itemize + +@end deftypefn + +@c pexecute.txh:272 +@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err}) + +An interface to permit the easy execution of a +single program. The return value and most of the parameters are as +for a call to @code{pex_run}. @var{flags} is restricted to a +combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and +@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if +@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will +be set to the exit status of the program. + +@end deftypefn + +@c pexecute.txh:228 +@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary}) + +Returns a @code{FILE} pointer which may be used to read the standard +error of the last program in the pipeline. When this is used, +@code{PEX_LAST} should not be used in a call to @code{pex_run}. After +this is called, @code{pex_run} may no longer be called with the same +@var{obj}. @var{binary} should be non-zero if the file should be +opened in binary mode. Don't call @code{fclose} on the returned file; +it will be closed by @code{pex_free}. + +@end deftypefn + +@c pexecute.txh:216 +@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) Returns a @code{FILE} pointer which may be used to read the standard output of the last program in the pipeline. When this is used, @@ -827,8 +852,132 @@ it will be closed by @code{pex_free}. @end deftypefn -@c pexecute.txh:173 -@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags) +@c pexecute.txh:33 +@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline. On success this returns +@code{NULL}. On failure it returns an error message, a statically +allocated string. + +@var{obj} is returned by a previous call to @code{pex_init}. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_LAST +@item PEX_LAST +This must be set on the last program in the pipeline. In particular, +it should be set when executing a single program. The standard output +of the program will be sent to @var{outname}, or, if @var{outname} is +@code{NULL}, to the standard output of the calling program. Do @emph{not} +set this bit if you want to call @code{pex_read_output} +(described below). After a call to @code{pex_run} with this bit set, +@var{pex_run} may no longer be called with the same @var{obj}. + +@vindex PEX_SEARCH +@item PEX_SEARCH +Search for the program using the user's executable search path. + +@vindex PEX_SUFFIX +@item PEX_SUFFIX +@var{outname} is a suffix. See the description of @var{outname}, +below. + +@vindex PEX_STDERR_TO_STDOUT +@item PEX_STDERR_TO_STDOUT +Send the program's standard error to standard output, if possible. + +@vindex PEX_BINARY_INPUT +@vindex PEX_BINARY_OUTPUT +@vindex PEX_BINARY_ERROR +@item PEX_BINARY_INPUT +@itemx PEX_BINARY_OUTPUT +@itemx PEX_BINARY_ERROR +The standard input (output or error) of the program should be read (written) in +binary mode rather than text mode. These flags are ignored on systems +which do not distinguish binary mode and text mode, such as Unix. For +proper behavior these flags should match appropriately---a call to +@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a +call using @code{PEX_BINARY_INPUT}. + +@vindex PEX_STDERR_TO_PIPE +@item PEX_STDERR_TO_PIPE +Send the program's standard error to a pipe, if possible. This flag +cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This +flag can be specified only on the last program in pipeline. + +@end table + +@var{executable} is the program to execute. @var{argv} is the set of +arguments to pass to the program; normally @code{@var{argv}[0]} will +be a copy of @var{executable}. + +@var{outname} is used to set the name of the file to use for standard +output. There are two cases in which no output file will be used: + +@enumerate +@item +if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} +was set in the call to @code{pex_init}, and the system supports pipes + +@item +if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is +@code{NULL} +@end enumerate + +@noindent +Otherwise the code will use a file to hold standard +output. If @code{PEX_LAST} is not set, this file is considered to be +a temporary file, and it will be removed when no longer needed, unless +@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. + +There are two cases to consider when setting the name of the file to +hold standard output. + +@enumerate +@item +@code{PEX_SUFFIX} is set in @var{flags}. In this case +@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter +to @code{pex_init} was not @code{NULL}, then the output file name is +the concatenation of @var{tempbase} and @var{outname}. If +@var{tempbase} was @code{NULL}, then the output file name is a random +file name ending in @var{outname}. + +@item +@code{PEX_SUFFIX} was not set in @var{flags}. In this +case, if @var{outname} is not @code{NULL}, it is used as the output +file name. If @var{outname} is @code{NULL}, and @var{tempbase} was +not NULL, the output file name is randomly chosen using +@var{tempbase}. Otherwise the output file name is chosen completely +at random. +@end enumerate + +@var{errname} is the file name to use for standard error output. If +it is @code{NULL}, standard error is the same as the caller's. +Otherwise, standard error is written to the named file. + +On an error return, the code sets @code{*@var{err}} to an @code{errno} +value, or to 0 if there is no relevant @code{errno}. + +@end deftypefn + +@c pexecute.txh:142 +@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline, permitting the environment for the +program to be specified. Behaviour and parameters not listed below are +as for @code{pex_run}. + +@var{env} is the environment for the child process, specified as an array of +character pointers. Each element of the array should point to a string of the +form @code{VAR=VALUE}, with the exception of the last element that must be +@code{NULL}. + +@end deftypefn + +@c pexecute.txh:284 +@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int @var{flags}) This is the old interface to execute one or more programs. It is still supported for compatibility purposes, but is no longer @@ -837,7 +986,7 @@ documented. @end deftypefn @c strsignal.c:539 -@deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) +@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) Print @var{message} to the standard error, followed by a colon, followed by the description of the signal specified by @var{signo}, @@ -855,7 +1004,7 @@ name is unset/removed. @end deftypefn -@c pexecute.txh:181 +@c pexecute.txh:292 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) Another part of the old execution interface. @@ -877,7 +1026,7 @@ control over the state of the random number generator. @end deftypefn -@c concat.c:167 +@c concat.c:173 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) Same as @code{concat}, except that if @var{optr} is not @code{NULL} it @@ -1180,6 +1329,53 @@ translation is found, returns 0. @end deftypefn +@c strverscmp.c:25 +@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +The @code{strverscmp} function compares the string @var{s1} against +@var{s2}, considering them as holding indices/version numbers. Return +value follows the same conventions as found in the @code{strverscmp} +function. In fact, if @var{s1} and @var{s2} contain no digits, +@code{strverscmp} behaves like @code{strcmp}. + +Basically, we compare strings normally (character by character), until +we find a digit in each string - then we enter a special comparison +mode, where each sequence of digits is taken as a whole. If we reach the +end of these two parts without noticing a difference, we return to the +standard comparison mode. There are two types of numeric parts: +"integral" and "fractional" (those begin with a '0'). The types +of the numeric parts affect the way we sort them: + +@itemize @bullet +@item +integral/integral: we compare values as you would expect. + +@item +fractional/integral: the fractional part is less than the integral one. +Again, no surprise. + +@item +fractional/fractional: the things become a bit more complex. +If the common prefix contains only leading zeroes, the longest part is less +than the other one; else the comparison behaves normally. +@end itemize + +@smallexample +strverscmp ("no digit", "no digit") + @result{} 0 // @r{same behavior as strcmp.} +strverscmp ("item#99", "item#100") + @result{} <0 // @r{same prefix, but 99 < 100.} +strverscmp ("alpha1", "alpha001") + @result{} >0 // @r{fractional part inferior to integral one.} +strverscmp ("part1_f012", "part1_f01") + @result{} >0 // @r{two fractional parts.} +strverscmp ("foo.009", "foo.0") + @result{} <0 // @r{idem, but with leading zeroes only.} +@end smallexample + +This function is especially useful when dealing with filename sorting, +because filenames frequently hold indices/version numbers. +@end deftypefun + @c tmpnam.c:3 @deftypefn Supplemental char* tmpnam (char *@var{s})