[BACK]Return to exec.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/exec.3, Revision 1.29

1.29    ! wiz         1: .\"    $NetBSD: exec.3,v 1.28 2017/09/17 11:45:10 abhinav Exp $
1.5       cgd         2: .\"
                      3: .\" Copyright (c) 1991, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
1.18      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        15: .\"    may be used to endorse or promote products derived from this software
                     16: .\"    without specific prior written permission.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     21: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     28: .\" SUCH DAMAGE.
                     29: .\"
1.5       cgd        30: .\"     @(#)exec.3     8.3 (Berkeley) 1/24/94
1.1       cgd        31: .\"
1.23      christos   32: .Dd September 26, 2014
1.1       cgd        33: .Dt EXEC 3
                     34: .Os
                     35: .Sh NAME
                     36: .Nm execl ,
                     37: .Nm execlp ,
1.28      abhinav    38: .Nm execlpe ,
1.1       cgd        39: .Nm execle ,
                     40: .Nm exect ,
                     41: .Nm execv ,
1.28      abhinav    42: .Nm execvp ,
                     43: .Nm execvpe
1.1       cgd        44: .Nd execute a file
1.9       perry      45: .Sh LIBRARY
                     46: .Lb libc
1.1       cgd        47: .Sh SYNOPSIS
1.17      wiz        48: .In unistd.h
1.1       cgd        49: .Vt extern char **environ;
                     50: .Ft int
                     51: .Fn execl "const char *path" "const char *arg" ...
                     52: .Ft int
                     53: .Fn execlp "const char *file" "const char *arg" ...
                     54: .Ft int
1.23      christos   55: .Fn execlpe "const char *path" "const char *arg" ... "char *const envp[]"
                     56: .Ft int
1.1       cgd        57: .Fn execle "const char *path" "const char *arg" ... "char *const envp[]"
                     58: .Ft int
1.5       cgd        59: .Fn exect "const char *path" "char *const argv[]"  "char *const envp[]"
1.1       cgd        60: .Ft int
                     61: .Fn execv "const char *path" "char *const argv[]"
                     62: .Ft int
                     63: .Fn execvp "const char *file" "char *const argv[]"
1.23      christos   64: .Ft int
1.25      wiz        65: .Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]"
1.1       cgd        66: .Sh DESCRIPTION
                     67: The
1.22      abs        68: .Fn exec
1.1       cgd        69: family of functions replaces the current process image with a
                     70: new process image.
                     71: The functions described in this manual page are front-ends for the function
                     72: .Xr execve 2 .
                     73: (See the manual page for
1.10      fair       74: .Xr execve 2
1.19      perry      75: for detailed information about the replacement of the current process.
                     76: The
                     77: .Xr script 7
                     78: manual page provides detailed information about the execution of
                     79: interpreter scripts.)
1.1       cgd        80: .Pp
                     81: The initial argument for these functions is the pathname of a file which
                     82: is to be executed.
                     83: .Pp
                     84: The
                     85: .Fa "const char *arg"
                     86: and subsequent ellipses in the
                     87: .Fn execl ,
                     88: .Fn execlp ,
1.23      christos   89: .Fn execlpe ,
1.1       cgd        90: and
                     91: .Fn execle
                     92: functions can be thought of as
                     93: .Em arg0 ,
                     94: .Em arg1 ,
                     95: \&...,
                     96: .Em argn .
1.26      wiz        97: Together they describe a list of one or more pointers to NUL-terminated
1.1       cgd        98: strings that represent the argument list available to the executed program.
                     99: The first argument, by convention, should point to the file name associated
                    100: with the file being executed.
                    101: The list of arguments
                    102: .Em must
                    103: be terminated by a
                    104: .Dv NULL
                    105: pointer.
                    106: .Pp
                    107: The
                    108: .Fn exect ,
                    109: .Fn execv ,
1.23      christos  110: .Fn execvp ,
1.1       cgd       111: and
1.23      christos  112: .Fn execvpe
1.26      wiz       113: functions provide an array of pointers to NUL-terminated strings that
1.1       cgd       114: represent the argument list available to the new program.
                    115: The first argument, by convention, should point to the file name associated
1.11      groo      116: with the file being executed.
1.1       cgd       117: The array of pointers
                    118: .Sy must
                    119: be terminated by a
                    120: .Dv NULL
                    121: pointer.
                    122: .Pp
                    123: The
1.24      christos  124: .Fn execle ,
1.25      wiz       125: .Fn execlpe ,
1.26      wiz       126: .Fn exect ,
1.1       cgd       127: and
1.26      wiz       128: .Fn execvpe
1.1       cgd       129: functions also specify the environment of the executed process by following
                    130: the
                    131: .Dv NULL
                    132: pointer that terminates the list of arguments in the parameter list
                    133: or the pointer to the argv array with an additional parameter.
1.26      wiz       134: This additional parameter is an array of pointers to NUL-terminated strings
1.1       cgd       135: and
                    136: .Em must
                    137: be terminated by a
                    138: .Dv NULL
                    139: pointer.
                    140: The other functions take the environment for the new process image from the
                    141: external variable
                    142: .Va environ
                    143: in the current process.
                    144: .Pp
                    145: Some of these functions have special semantics.
                    146: .Pp
                    147: The functions
1.23      christos  148: .Fn execlp ,
                    149: .Fn execlpe ,
1.25      wiz       150: .Fn execvp ,
1.1       cgd       151: and
1.23      christos  152: .Fn execvpe
1.1       cgd       153: will duplicate the actions of the shell in searching for an executable file
                    154: if the specified file name does not contain a slash
1.12      wiz       155: .Dq Li \&/
1.1       cgd       156: character.
1.12      wiz       157: The search path is the path specified in the environment by the
                    158: .Ev PATH
1.1       cgd       159: variable.
1.14      yamt      160: If this variable isn't specified,
1.16      wiz       161: .Va _PATH_DEFPATH
                    162: from
1.21      joerg     163: .In paths.h
1.14      yamt      164: is used instead, its value being:
1.16      wiz       165: .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin .
1.4       jtc       166: In addition, certain errors are treated specially.
1.1       cgd       167: .Pp
                    168: If permission is denied for a file (the attempted
1.10      fair      169: .Xr execve 2
1.1       cgd       170: returned
                    171: .Er EACCES ) ,
                    172: these functions will continue searching the rest of
                    173: the search path.
                    174: If no other file is found, however, they will return with the global variable
                    175: .Va errno
                    176: set to
                    177: .Er EACCES .
                    178: .Pp
                    179: If the header of a file isn't recognized (the attempted
1.10      fair      180: .Xr execve 2
1.1       cgd       181: returned
                    182: .Er ENOEXEC ) ,
                    183: these functions will execute the shell with the path of
                    184: the file as its first argument.
                    185: (If this attempt fails, no further searching is done.)
                    186: .Pp
                    187: If the file is currently busy (the attempted
1.10      fair      188: .Xr execve 2
1.1       cgd       189: returned
                    190: .Er ETXTBUSY ) ,
                    191: these functions will sleep for several seconds,
                    192: periodically re-attempting to execute the file.
                    193: .Pp
                    194: The function
                    195: .Fn exect
                    196: executes a file with the program tracing facilities enabled (see
                    197: .Xr ptrace 2 ) .
                    198: .Sh RETURN VALUES
                    199: If any of the
1.22      abs       200: .Fn exec
1.1       cgd       201: functions returns, an error will have occurred.
                    202: The return value is \-1, and the global variable
                    203: .Va errno
                    204: will be set to indicate the error.
                    205: .Sh FILES
1.3       jtc       206: .Bl -tag -width /bin/sh -compact
1.1       cgd       207: .It Pa /bin/sh
                    208: The shell.
                    209: .El
                    210: .Sh COMPATIBILITY
                    211: Historically, the default path for the
                    212: .Fn execlp
1.23      christos  213: .Fn execlpe ,
                    214: .Fn execvp ,
1.1       cgd       215: and
1.23      christos  216: .Fn execvpe
1.1       cgd       217: functions was
                    218: .Dq Pa :/bin:/usr/bin .
1.15      yamt      219: This was changed to improve security and behaviour.
1.1       cgd       220: .Pp
                    221: The behavior of
1.23      christos  222: .Fn execlp ,
                    223: .Fn execlpe ,
                    224: .Fn execvp ,
1.1       cgd       225: and
1.23      christos  226: .Fn execvpe
1.1       cgd       227: when errors occur while attempting to execute the file is historic
                    228: practice, but has not traditionally been documented and is not specified
1.29    ! wiz       229: by the POSIX standard.
1.1       cgd       230: .Pp
                    231: Traditionally, the functions
1.23      christos  232: .Fn execlp ,
                    233: .Fn execlpe ,
                    234: .Fn execvp ,
1.1       cgd       235: and
1.23      christos  236: .Fn execvpe
1.1       cgd       237: ignored all errors except for the ones described above and
                    238: .Er ENOMEM
                    239: and
                    240: .Er E2BIG ,
                    241: upon which they returned.
                    242: They now return if any error other than the ones described above occurs.
1.22      abs       243: .Sh ERRORS
                    244: .Fn execl ,
                    245: .Fn execle ,
1.23      christos  246: .Fn execlp ,
                    247: .Fn execlpe ,
1.25      wiz       248: .Fn execvp ,
1.22      abs       249: and
1.23      christos  250: .Fn execvpe
1.22      abs       251: may fail and set
                    252: .Va errno
                    253: for any of the errors specified for the library functions
                    254: .Xr execve 2
                    255: and
                    256: .Xr malloc 3 .
                    257: .Pp
                    258: .Fn exect
                    259: and
                    260: .Fn execv
                    261: may fail and set
                    262: .Va errno
                    263: for any of the errors specified for the library function
                    264: .Xr execve 2 .
                    265: .Sh SEE ALSO
                    266: .Xr sh 1 ,
                    267: .Xr execve 2 ,
                    268: .Xr fork 2 ,
                    269: .Xr ptrace 2 ,
                    270: .Xr environ 7 ,
                    271: .Xr script 7
1.1       cgd       272: .Sh STANDARDS
1.8       enami     273: .Fn execl ,
1.1       cgd       274: .Fn execv ,
                    275: .Fn execle ,
1.25      wiz       276: .Fn execlp ,
1.1       cgd       277: and
                    278: .Fn execvp
                    279: conform to
1.6       kleink    280: .St -p1003.1-90 .
1.23      christos  281: .Pp
                    282: The
                    283: .Fn execlpe
                    284: function appeared first in QNX and the
                    285: .Fn execvpe
1.25      wiz       286: function exists on both
1.27      rin       287: .Nx
1.23      christos  288: and QNX.

CVSweb <webmaster@jp.NetBSD.org>