path.3

Introduction to Library Functions                         PATH(3)

NAME
     path - file path routines

SYNOPSIS
          #include <ast.h>

          char*     pathaccess(char* path, const char* dirs, const char* a, const char* b, int mode);
          char*     pathbin(void);
          char*     pathcanon(char* path, int flags);
          char*     pathcat(char* path, const char* dirs, int sep, const char* a, const char* b);
          char*     pathcd(char* path, const char* home);
          int       pathcheck(const char* package, const char* tool, Pathcheck_t* pc);
          int       pathgetlink(const char* name, char* buf, int siz);
          char*     pathkey(char* key, char* attr, const char* lang, const char* path);
          char*     pathnext(char* path, char* extra, long* visits);
          char*     pathpath(char* path, const char* p, const char* a, int mode);
          char*     pathprobe(char* path, char* attr, const char* lang, const char* tool, const char* proc, int op);
          char*     pathrepl(char* path, const char* match, const char* replace);
          int       pathsetlink(const char* text, char* name);
          char*     pathshell(void);
          int       pathstat(const char* path, struct stat* st);
          char*     pathtemp(char* path, const char* dir, const char* pfx);

DESCRIPTION
     These routines operate on file path names.  Path buffers are
     assumed  to  be  of  size  PATH_MAX.  <ast.h> always defines
     PATH_MAX, even if it  indeterminant  on  the  local  system.
     Yes,  this  was probably a bad choice, but it was made about
     10 years ago.  We will probably  move  to  a  <stk.h>  based
     implementation.

     pathaccess constructs a path in path to the  file  a/b  with
     access  mode  using  the  :   separated directories in dirs.
     Both a and b may be 0.  mode is the inclusive-or of:

     F_OK File exists.

     R_OK Read permission on file.

     W_OK Write permission on file.

     X_OK Execute permission on file.

     PATH_REGULAR
          A regular file.

     PATH_ABSOLUTE
          Generated path name is rooted at /.  path is  returned,
          0 on error.

     pathbin returns a pointer to the :  separated list of direc-
     tories   to   search  for  executable  commands.   The  PATH

SunOS 5.10                Last change:                          1

Introduction to Library Functions                         PATH(3)

     environment variable is first  consulted.   If  not  defined
     then  confstr(_CS_PATH,...)   is  used.   A  valid string is
     always returned.

     pathcanon canonicalizes the path path in place.   A  pointer
     to  the trailing 0 in the canonicalized path is returned.  A
     canonical path has:  redundant .  and / removed;  ..   moved
     to  the  front;  /..   preserved  for  super root hacks; ...
     resolved if fs3d(3) is enabled.  flags is  the  inclusive-or
     of:

     PATH_DOTDOT
          Each ..  is checked for access.

     PATH_EXISTS
          Path must exist at each component.

     PATH_PHYSICAL
          Symbolic links are resolved at each component.

     0 is returned on error.  If an error occurs  and  either  of
     PATH_DOTDOT or PATH_EXISTS is set then path will contain the
     components following the failure point.

     pathcat concatenates the first sep separated path  component
     in  dirs  with  the  path components a and b into path.  The
     path is constructed in path by  separating  each  path  com-
     ponent  with  /.   Both  a and b may be 0.  A pointer to the
     next sep separated component in dirs  is  returned,  0  when
     there  are  no  more components.  pathcat is used by pathac-
     cess.

     pathcd sets  the  current  working  directory  to  path  via
     chdir(2).   If path is longer than PATH_MAX then it is split
     up into a sequence of relative paths and chdir is called  on
     each of these.  For any given system, if you got to a direc-
     tory, then pathcd can get you back,  modulo  permission  and
     link changes.

     pathcheck is a stub for license libraries.  See license(3).

     pathgetlink returns the 0-terminated symbolic link text  for
     path  in the buffer bu of size siz.  The link text length is
     returned on  success,  -1  on  error.   Weird  universe  (1)
     interactions with dynamic symbolic links are handled by con-
     verting non-standard dynamic  link  text  to  pathsetsymlink
     converts in the other direction.

     pathkey generates in key a 14  character  lookup  key  (plus
     terminating  0)  for the language lang processor in path.  A
     poihter to the key is returned, 0 on error.   If  key  ==  0
     then   space  is  allocated  via  malloc(3).   Key  specific

SunOS 5.10                Last change:                          2

Introduction to Library Functions                         PATH(3)

     attribute name=value pairs are copied into attr if  attr  !=
     0.

     pathpath constructs in path a path to p with access(2)  mode
     mode  using  the directories from pathbin().  If a != 0 then
     a, argv[0] (if available via optget(3)), and the _  environ-
     ment  variable  (set  by  ksh(1))  are used for related root
     searching.  If p also contains a /  then  ../p  is  searched
     for.

     pathprobe generates in path the full path name of  the  tool
     specific  probe(1)  information  file  for the lang langauge
     processor proc.  If path == 0 then space  is  allocated  via
     malloc(3).  Probe attribute name=value pairs are copied into
     attr if attr != 0.  op may be one of:

     -1   return the path name with no access checks  or  genera-
          tion

     0    message  emitted  information  must  be  generated  via
          probe(1)

     1    no message  emitted  information  must  be  probed  via
          probe(1)

     0 is returned if the information does not exist  and  cannot
     be generated.

     pathrepl  does  an  in-place  replacement   of   the   first
     occurrence of /match/ with /replace/ in path.

     pathsetlink creates a symbolic link text in the  path  name.
     See  pathgetlink  above  for  weird universe(1) interactions
     hidden by this routine.

     pathshell returns a pointer to the pathname  for  the  shell
     for  the current process.  The SHELL environment variable is
     first  consulted,   but   is   rejected   under   suspicious
     ownership/setuid  conditions  of  if  it  seems  to point to
     csh(1); otherwise confstr(_CS_SHELL,...)  is used.  A  valid
     string is always returned.

     pathstat first tries and if that fails it tries The stat  or
     lstat return value is returned.

     pathtemp generates in path a temporary file path name of the
     form  dir/pfx<pid>.<suf> where the length of pfx, if !=0, is
     limited to 5, the length of <pid> (the base  64  representa-
     tion  of  the current process id) is limited to 3, and <suf>
     (an internally generated suffix that avoid file  confilicts)
     is  limited  to  3.  The generated path name conforms to the
     classic UNIX 14 char and the DOS 8.3 limitations.  Both  dir

SunOS 5.10                Last change:                          3

Introduction to Library Functions                         PATH(3)

     and pfx may be 0.  access(2) is used to avoid file conflicts
     but the generated path name is not  created,  so  you  could
     lose in a race.

SEE ALSO
     3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)

SunOS 5.10                Last change:                          4

Generated by GNU enscript 1.6.4.