Sender: rich AT phekda DOT freeserve DOT co DOT uk
Message-ID: <39B0DC84.389C0357@phekda.freeserve.co.uk>
Date: Sat, 02 Sep 2000 11:55:00 +0100
From: Richard Dawe <rich AT phekda DOT freeserve DOT co DOT uk>
X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.14 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: DJGPP workers <djgpp-workers AT delorie DOT com>
Subject: Doc for __dosexec_find_on_path()
Content-Type: multipart/mixed;
 boundary="------------A891D0660F1806D7B7A372DA"
Reply-To: djgpp-workers AT delorie DOT com

This is a multi-part message in MIME format.
--------------A891D0660F1806D7B7A372DA
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hello.

Please find attached a slight elaboration of Eli's description of
__dosexec_find_on_path(). Eli posted his description to
comp.os.msdos.djgpp in response to the thread about a port of GNU which on
21st September.

I suggest that this file is called dxfndpth.txh, but the name isn't that
important. I also suggest that dosexec.txh is renamed to spawn.txh, since
it describes the spawn*() functions rather than any of the *dosexec*()
functions.

While writing this document, I noticed that dosexec.c does not have an
interpreter for .cmd files. I think these are Windows NT batch files,
perhaps OS/2. I wonder how easy it would be to add support for these? I
have neither NT or OS/2 easily accessible BTW.

I was also wondering about my dpmi.h patch. I sent this to djgpp-workers
during the gcc cacophony. Basically the changes were to make all the
structures in dpmi.h packed. There seemed to be agreement that this change
was a Good Idea. Has this just been forgotten about or do I need to test
it more? I rebuilt libc, libsocket with it and it seemed to work OK. The
coverage of DPMI functions by libsocket is a little limited though.

Thanks, bye, Rich =]

-- 
Richard Dawe
[ mailto:richdawe AT bigfoot DOT com | http://www.bigfoot.com/~richdawe/ ]
--------------A891D0660F1806D7B7A372DA
Content-Type: text/plain; charset=us-ascii;
 name="dxfndpth.txh"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="dxfndpth.txh"

@node __dosexec_find_on_path, process
@subheading Syntax

@example
#include <stdio.h>
#include <libc/dosexec.h>

char *__dosexec_find_on_path(const char *program,
                             char *envp[], char *buf);
@end example

@subheading Description

This function searches for a program using a given path.  The program is
searched for using a known set of exectuable extensions, e.g. @file{.exe}.
These executable extensions are described for the @code{spawn*()} function
(@pxref{spawn*}).

Pass the program name in @var{program}, the environment array in @var{envp}
and the output buffer in @var{buf}.  @var{envp} is an array of pointers
to the environment; it must be terminated with a @code{NULL} pointer.
@var{buf} must be large enough to hold @samp{FILENAME_MAX} bytes.

@var{envp} controls where @code{__dosexec_find_on_path()} looks for
the program.  If @var{envp} is @code{NULL}, then only the current directory
is searched.  If @var{envp} contains the @samp{PATH} environment variable
in the form @samp{PATH=@dots{}}, then its directories are also searched.
The global variable @code{environ} is usually passed for @var{envp}.

@subheading Return Value

If the function finds the program, with or without one of the known executable
extensions, either in the current directory or along the @samp{PATH}
as recorded in @var{envp}, it puts the full pathname into @var{buf}
and returns a pointer to @var{buf}.  Otherwise, it returns @code{NULL}.

@subheading Portability

@portability !ansi, !posix

--------------A891D0660F1806D7B7A372DA--