1  /* Locating a program in PATH.
       2     Copyright (C) 2001-2003, 2009-2022 Free Software Foundation, Inc.
       3     Written by Bruno Haible <haible@clisp.cons.org>, 2001.
       4  
       5     This file is free software: you can redistribute it and/or modify
       6     it under the terms of the GNU Lesser General Public License as
       7     published by the Free Software Foundation; either version 2.1 of the
       8     License, or (at your option) any later version.
       9  
      10     This file is distributed in the hope that it will be useful,
      11     but WITHOUT ANY WARRANTY; without even the implied warranty of
      12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      13     GNU Lesser General Public License for more details.
      14  
      15     You should have received a copy of the GNU Lesser General Public License
      16     along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
      17  
      18  #ifndef _FINDPROG_H
      19  #define _FINDPROG_H
      20  
      21  #include <stdbool.h>
      22  
      23  #ifdef __cplusplus
      24  extern "C" {
      25  #endif
      26  
      27  
      28  /* Looks up a program in the PATH.
      29     Attempts to determine the pathname that would be called by execlp/execvp
      30     of PROGNAME.  If successful, it returns a pathname containing a slash
      31     (either absolute or relative to the current directory).  Otherwise, it
      32     returns PROGNAME unmodified.
      33     Because of the latter case, callers should use execlp/execvp, not
      34     execl/execv on the returned pathname.
      35     The returned string is freshly malloc()ed if it is != PROGNAME.  */
      36  extern const char *find_in_path (const char *progname);
      37  
      38  /* Looks up a program in the given PATH-like string.
      39  
      40     The PATH argument consists of a list of directories, separated by ':' or
      41     (on native Windows) by ';'.  An empty PATH element designates the current
      42     directory.  A null PATH is equivalent to an empty PATH, that is, to the
      43     singleton list that contains only the current directory.
      44  
      45     If DIRECTORY is not NULL, all relative filenames (i.e. PROGNAME when it
      46     contains a slash, and the PATH elements) are considered relative to
      47     DIRECTORY instead of relative to the current directory of this process.
      48  
      49     Determines the pathname that would be called by execlp/execvp of PROGNAME.
      50     - If successful, it returns a pathname containing a slash (either absolute
      51       or relative to the current directory).  The returned string can be used
      52       with either execl/execv or execlp/execvp.  It is freshly malloc()ed if it
      53       is != PROGNAME.
      54     - Otherwise, it sets errno and returns NULL.
      55       Specific errno values include:
      56         - ENOENT: means that the program's file was not found.
      57         - EACCES: means that the program's file cannot be accessed (due to some
      58           issue with one of the ancestor directories) or lacks the execute
      59           permissions.
      60         - ENOMEM: means out of memory.
      61     If OPTIMIZE_FOR_EXEC is true, the function saves some work, under the
      62     assumption that the resulting pathname will not be accessed directly,
      63     only through execl/execv or execlp/execvp.
      64  
      65     Here, a "slash" means:
      66       - On POSIX systems excluding Cygwin: a '/',
      67       - On Windows, OS/2, DOS platforms: a '/' or '\'. */
      68  extern const char *find_in_given_path (const char *progname, const char *path,
      69                                         const char *directory,
      70                                         bool optimize_for_exec);
      71  
      72  
      73  #ifdef __cplusplus
      74  }
      75  #endif
      76  
      77  #endif /* _FINDPROG_H */