LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    environ

    
    
    

    SYNOPSIS

           #include <unistd.h>
    
           extern char **environ;
           int execl(const char *path, const char *arg0, ... /*, (char *)0 */);
           int execv(const char *path, char *const argv[]);
           int execle(const char *path, const char *arg0, ... /*,
                  (char *)0, char *const envp[]*/);
           int execve(const char *path, char *const argv[], char *const envp[]);
           int execlp(const char *file, const char *arg0, ... /*, (char *)0 */);
           int execvp(const char *file, char *const argv[]);
    
    
    

    DESCRIPTION

           The  exec  family  of functions shall replace the current process image
           with a new process image. The new image shall  be  constructed  from  a
           regular, executable file called the new process image file. There shall
           be no return from a successful exec, because the calling process  image
           is overlaid by the new process image.
    
           When  a  C-language  program  is  executed as a result of this call, it
           shall be entered as a C-language function call as follows:
    
                  int main (int argc, char *argv[]);
    
           where argc is the argument count and argv  is  an  array  of  character
           pointers  to the arguments themselves. In addition, the following vari-
           able:
    
                  extern char **environ;
    
           is initialized as a pointer to an array of character  pointers  to  the
           environment strings. The argv and environ arrays are each terminated by
           a null pointer. The null pointer terminating  the  argv  array  is  not
           counted in argc.
    
           Conforming  multi-threaded applications shall not use the environ vari-
           able to access or modify  any  environment  variable  while  any  other
           thread  is  concurrently modifying any environment variable.  A call to
           any function dependent on any environment variable shall be  considered
           a use of the environ variable to access that environment variable.
    
           The  arguments  specified  by  a program with one of the exec functions
           shall be passed on to the new process image in the corresponding main()
           arguments.
    
           The  argument path points to a pathname that identifies the new process
           image file.
    
           The argument file is used to construct a pathname that  identifies  the
           command shall be as if the process invoked the sh utility using execl()
           as follows:
    
                  execl(<shell path>, arg0, file, arg1, ..., (char *)0);
    
           where <shell path> is an unspecified pathname for the sh utility,  file
           is  the  process image file, and for execvp(), where arg0, arg1, and so
           on correspond to the values passed to execvp() in argv[0], argv[1], and
           so on.
    
           The  arguments  represented by arg0,... are pointers to null-terminated
           character strings. These strings shall  constitute  the  argument  list
           available  to  the  new process image. The list is terminated by a null
           pointer. The argument arg0 should point to a filename that  is  associ-
           ated with the process being started by one of the exec functions.
    
           The  argument argv is an array of character pointers to null-terminated
           strings. The application shall ensure that  the  last  member  of  this
           array  is  a  null pointer. These strings shall constitute the argument
           list available to the new process image.  The value in  argv[0]  should
           point  to  a filename that is associated with the process being started
           by one of the exec functions.
    
           The argument envp is an array of character pointers to  null-terminated
           strings.  These  strings  shall  constitute the environment for the new
           process image. The envp array is terminated by a null pointer.
    
           For those forms not containing an envp pointer ( execl(), execv(), exe-
           clp(),  and  execvp()), the environment for the new process image shall
           be taken from the external variable environ in the calling process.
    
           The number of bytes available for the new  process'  combined  argument
           and  environment  lists  is  {ARG_MAX}.  It  is  implementation-defined
           whether null terminators, pointers,  and/or  any  alignment  bytes  are
           included in this total.
    
           File descriptors open in the calling process image shall remain open in
           the new process image, except  for  those  whose  close-on-  exec  flag
           FD_CLOEXEC  is  set.  For  those file descriptors that remain open, all
           attributes of the open file description remain unchanged. For any  file
           descriptor  that is closed for this reason, file locks are removed as a
           result of the close as described  in  close()  .  Locks  that  are  not
           removed by closing of file descriptors remain unchanged.
    
           If  file descriptors 0, 1, and 2 would otherwise be closed after a suc-
           cessful call to one of the exec family of functions, and the  new  pro-
           cess image file has the set-user-ID or set-group-ID file mode bits set,
            and the ST_NOSUID bit is not set for the file  system  containing  the
           new  process  image file,  implementations may open an unspecified file
           for each of these file descriptors in the new process image.
    
    
           Signals set to the default action  (SIG_DFL)  in  the  calling  process
           image  shall  be  set  to  the default action in the new process image.
           Except for SIGCHLD, signals set to be ignored (SIG_IGN) by the  calling
           process image shall be set to be ignored by the new process image. Sig-
           nals set to be caught by the calling process image shall be set to  the
           default  action  in  the  new  process  image  (see <signal.h>). If the
           SIGCHLD signal is set to be ignored by the calling process image, it is
           unspecified  whether  the SIGCHLD signal is set to be ignored or to the
           default action in the new process image.   After a successful  call  to
           any  of  the  exec functions, alternate signal stacks are not preserved
           and the SA_ONSTACK flag shall be cleared for all signals.
    
           After a successful call to any of the  exec  functions,  any  functions
           previously registered by atexit() are no longer registered.
    
           If the ST_NOSUID bit is set for the file system containing the new pro-
           cess image file, then the effective user ID, effective group ID,  saved
           set-user-ID,  and  saved  set-group-ID are unchanged in the new process
           image. Otherwise,  if the set-user-ID mode bit of the new process image
           file  is  set,  the effective user ID of the new process image shall be
           set to the user ID of the new process image  file.  Similarly,  if  the
           set-group-ID  mode bit of the new process image file is set, the effec-
           tive group ID of the new process image shall be set to the group ID  of
           the  new  process image file. The real user ID, real group ID, and sup-
           plementary group IDs of the new process image shall remain the same  as
           those of the calling process image. The effective user ID and effective
           group ID of the new process image shall be saved  (as  the  saved  set-
           user-ID and the saved set-group-ID) for use by setuid().
    
           Any  shared memory segments attached to the calling process image shall
           not be attached to the new process image.
    
           Any named semaphores open in the calling process shall be closed as  if
           by appropriate calls to sem_close().
    
           Any  blocks of typed memory that were mapped in the calling process are
           unmapped, as if munmap() was implicitly called to unmap them.
    
           Memory locks established by the calling process via calls to mlockall()
           or  mlock()  shall  be removed. If locked pages in the address space of
           the calling process are also mapped into the address  spaces  of  other
           processes  and  are locked by those processes, the locks established by
           the other processes shall be unaffected by the call by this process  to
           the  exec  function.  If  the exec function fails, the effect on memory
           locks is unspecified.
    
           Memory mappings created in the process are unmapped before the  address
           space is rebuilt for the new process image.
    
           For  the  SCHED_FIFO  and  SCHED_RR scheduling policies, the policy and
           priority settings shall not be changed by a call to an  exec  function.
           shall the new process image created by the exec function be affected by
           the presence of outstanding asynchronous I/O operations at the time the
           exec function is called. Whether any I/O is canceled, and which I/O may
           be canceled upon exec, is implementation-defined.
    
           The  new  process image shall inherit the CPU-time clock of the calling
           process image. This inheritance means that the process  CPU-time  clock
           of the process being exec-ed shall not be reinitialized or altered as a
           result of the exec function other than to reflect the time spent by the
           process executing the exec function itself.
    
           The  initial  value  of the CPU-time clock of the initial thread of the
           new process image shall be set to zero.
    
           If the calling process is being traced, the  new  process  image  shall
           continue  to  be traced into the same trace stream as the original pro-
           cess image, but the new process image shall not inherit the mapping  of
           trace  event  names to trace event type identifiers that was defined by
           calls to the posix_trace_eventid_open() or  the  posix_trace_trid_even-
           tid_open() functions in the calling process image.
    
           If the calling process is a trace controller process, any trace streams
           that were created  by  the  calling  process  shall  be  shut  down  as
           described in the posix_trace_shutdown() function.
    
           The  new  process  shall inherit at least the following attributes from
           the calling process image:
    
            * Nice value (see nice() )
    
            * semadj values (see semop() )
    
            * Process ID
    
            * Parent process ID
    
            * Process group ID
    
            * Session membership
    
            * Real user ID
    
            * Real group ID
    
    
            * File size limit (see ulimit() )
    
            * Process signal mask (see sigprocmask() )
    
            * Pending signal (see sigpending() )
    
            * tms_utime, tms_stime, tms_cutime, and tms_cstime (see times() )
    
            * Resource limits
    
            * Controlling terminal
    
            * Interval timers
    
           All   other   process   attributes   defined   in   this   volume    of
           IEEE Std 1003.1-2001  shall  be  the  same  in  the new and old process
           images. The inheritance of process attributes not defined by this  vol-
           ume of IEEE Std 1003.1-2001 is implementation-defined.
    
           A  call  to  any exec function from a process with more than one thread
           shall result in all threads being terminated  and  the  new  executable
           image  being  loaded  and  executed.  No  destructor functions shall be
           called.
    
           Upon successful completion, the exec functions shall  mark  for  update
           the st_atime field of the file. If an exec function failed but was able
           to locate the process image file, whether the st_atime field is  marked
           for  update  is unspecified. Should the exec function succeed, the pro-
           cess image file shall be considered to have been  opened  with  open().
           The  corresponding close() shall be considered to occur at a time after
           this open, but before process termination or successful completion of a
           subsequent  call  to  one  of  the  exec  functions,  posix_spawn(), or
           posix_spawnp().  The argv[] and  envp[]  arrays  of  pointers  and  the
           strings  to which those arrays point shall not be modified by a call to
           one of the exec functions, except as a  consequence  of  replacing  the
           process image.
    
           The saved resource limits in the new process image are set to be a copy
           of the process' corresponding hard and soft limits.
    
    
    

    RETURN VALUE

           If one of the exec functions returns to the calling process  image,  an
           error  has  occurred;  the return value shall be -1, and errno shall be
           set to indicate the error.
           EINVAL The new process image file has the  appropriate  permission  and
                  has  a  recognized executable binary format, but the system does
                  not support execution of a file with this format.
    
           ELOOP  A loop exists in symbolic links encountered during resolution of
                  the path or file argument.
    
           ENAMETOOLONG
                  The length of the path or file arguments exceeds {PATH_MAX} or a
                  pathname component is longer than {NAME_MAX}.
    
           ENOENT A component of path or file does not name an  existing  file  or
                  path or file is an empty string.
    
           ENOTDIR
                  A component of the new process image file's path prefix is not a
                  directory.
    
           The exec functions, except for execlp() and execvp(), shall fail if:
    
           ENOEXEC
                  The new process image file has the appropriate access permission
                  but has an unrecognized format.
    
           The exec functions may fail if:
    
           ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
                  resolution of the path or file argument.
    
           ENAMETOOLONG
                  As a result of encountering a symbolic link in resolution of the
                  path  argument,  the  length  of the substituted pathname string
                  exceeded {PATH_MAX}.
    
           ENOMEM The new process image requires more memory than  is  allowed  by
                  the hardware or system-imposed memory management constraints.
    
           ETXTBSY
                  The  new  process  image  file is a pure procedure (shared text)
                  file that is currently open for writing by some process.
    
           The following sections are informative.
    
    
    

    EXAMPLES

       Using execl()
           The following example executes the ls command, specifying the  pathname
           of  the  executable ( /bin/ls) and using arguments supplied directly to
           the command to produce single-column output.
    
                  #include <unistd.h>
    
                  int ret;
                  char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
                  ...
                  ret = execle ("/bin/ls", "ls", "-l", (char *)0, env);
    
       Using execlp()
           The following example searches for the location of the ls command among
           the directories specified by the PATH environment variable.
    
                  #include <unistd.h>
    
                  int ret;
                  ...
                  ret = execlp ("ls", "ls", "-l", (char *)0);
    
       Using execv()
           The  following  example  passes  arguments to the ls command in the cmd
           array.
    
                  #include <unistd.h>
    
                  int ret;
                  char *cmd[] = { "ls", "-l", (char *)0 };
                  ...
                  ret = execv ("/bin/ls", cmd);
    
       Using execve()
           The following example passes arguments to the ls  command  in  the  cmd
           array,  and  specifies  the environment for the new process image using
           the env argument.
    
                  #include <unistd.h>
    
                  int ret;
                  char *cmd[] = { "ls", "-l", (char *)0 };
                  char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
                  ...
                  ret = execve ("/bin/ls", cmd, env);
    
       Using execvp()
           The following example searches for the location of the ls command among
           the  directories specified by the PATH environment variable, and passes
           arguments to the ls command in the cmd array.
           exec functions.
    
           Applications  that  require  other than the default POSIX locale should
           call setlocale() with  the  appropriate  parameters  to  establish  the
           locale of the new process.
    
           The environ array should not be accessed directly by the application.
    
           Applications  should  not  depend on file descriptors 0, 1, and 2 being
           closed after an exec. A future version may allow these file descriptors
           to be automatically opened for any process.
    
    
    

    RATIONALE

           Early  proposals  required  that  the value of argc passed to main() be
           "one or greater". This was driven by the same requirement in drafts  of
           the  ISO C  standard. In fact, historical implementations have passed a
           value of zero when no arguments are supplied to the caller of the  exec
           functions.   This  requirement  was removed from the ISO C standard and
           subsequently removed from this volume of IEEE Std 1003.1-2001 as  well.
           The  wording,  in  particular  the  use  of the word should, requires a
           Strictly Conforming POSIX Application to pass at least one argument  to
           the  exec  function, thus guaranteeing that argc be one or greater when
           invoked by such an application. In fact, this is good  practice,  since
           many existing applications reference argv[0] without first checking the
           value of argc.
    
           The requirement on a Strictly Conforming POSIX Application also  states
           that  the  value  passed as the first argument be a filename associated
           with the process being started.  Although  some  existing  applications
           pass  a  pathname rather than a filename in some circumstances, a file-
           name is more generally useful, since the common usage of argv[0] is  in
           printing  diagnostics.  In  some  cases  the filename passed is not the
           actual filename of the file; for example, many implementations  of  the
           login  utility  use  a  convention of prefixing a hyphen ( '-' ) to the
           actual filename, which  indicates  to  the  command  interpreter  being
           invoked that it is a "login shell".
    
           Historically  there  have  been  two ways that implementations can exec
           shell scripts.
    
           One common historical implementation is that the execl(), execv(), exe-
           cle(),  and  execve()  functions return an [ENOEXEC] error for any file
           not recognizable as executable, including a shell script. When the exe-
           clp()  and  execvp()  functions  encounter such a file, they assume the
           file to be a shell script and invoke a  known  command  interpreter  to
           interpret  such  files.  This  is now required by IEEE Std 1003.1-2001.
           These implementations of execvp() and execlp() only give the  [ENOEXEC]
           error in the rare case of a problem with the command interpreter's exe-
           cutable file. Because of these implementations, the [ENOEXEC] error  is
           not  mentioned  for  execlp() or execvp(), although implementations can
           still give it.
    
    
            2. If the process image file has appropriate permission and  is  in  a
               format  that is executable but not valid for this system (such as a
               recognized binary for another architecture), then this is an  error
               and errno is set to [EINVAL] (see later RATIONALE on [EINVAL]).
    
            3. If  the  process  image  file has appropriate permission but is not
               otherwise recognized:
    
                a. If this is a call to execlp() or execvp(), then they  invoke  a
                   command  interpreter  assuming that the process image file is a
                   shell script.
    
                b. If this is not a call to execlp() or execvp(),  then  an  error
                   occurs and errno is set to [ENOEXEC].
    
           Applications  that do not require to access their arguments may use the
           form:
    
                  main(void)
           as specified in the ISO C standard. However,  the  implementation  will
           always  provide  the  two arguments argc and argv, even if they are not
           used.
    
           Some implementations provide a third argument to  main()  called  envp.
           This  is  defined  as  a pointer to the environment. The ISO C standard
           specifies invoking main() with two arguments, so  implementations  must
           support   applications   written   this   way.  Since  this  volume  of
           IEEE Std 1003.1-2001 defines the global variable environ, which is also
           provided  by  historical  implementations and can be used anywhere that
           envp could be used, there is no functional need for the envp  argument.
           Applications should use the getenv() function rather than accessing the
           environment directly via either envp or  environ.  Implementations  are
           required  to  support  the two-argument calling sequence, but this does
           not prohibit an implementation from  supporting  envp  as  an  optional
           third argument.
    
           This  volume  of  IEEE Std 1003.1-2001  specifies  that  signals set to
           SIG_IGN remain set to SIG_IGN, and that  the  process  signal  mask  be
           unchanged  across an exec. This is consistent with historical implemen-
           tations, and it permits some useful functionality, such  as  the  nohup
           command.  However,  it  should be noted that many existing applications
           wrongly assume that they start with certain signals set to the  default
           action  and/or  unblocked.  In  particular, applications written with a
           simpler signal model that does not include blocking of signals, such as
           the  one in the ISO C standard, may not behave properly if invoked with
           some signals blocked. Therefore, it is best not to block or ignore sig-
           exec  functions  may  seem  to  be the natural choice, given that these
           functions do not modify either the array of pointers or the  characters
           to  which the function points, but this would disallow existing correct
           code. Instead, only the array of pointers is noted as constant. The ta-
           ble  of  assignment  compatibility  for dst= src derived from the ISO C
           standard summarizes the compatibility:
    
        dst:                char *[] const char *[] char *const[] const char *const[]
        src:
        char *[]            VALID    -              VALID         -
        const char *[]      -        VALID          -             VALID
        char * const []     -        -              VALID         -
        const char *const[] -        -              -             VALID
    
           Since all existing code has a source type matching the first  row,  the
           column  that gives the most valid combinations is the third column. The
           only other possibility is the fourth column, but using it would require
           a cast on the argv or envp arguments. It is unfortunate that the fourth
           column cannot be used, because the declaration a non-expert would natu-
           rally use would be that in the second row.
    
           The  ISO C standard and this volume of IEEE Std 1003.1-2001 do not con-
           flict on the use of environ, but  some  historical  implementations  of
           environ  may  cause  a  conflict.  As long as environ is treated in the
           same way as an entry point (for example, fork()), it conforms  to  both
           standards.   A  library can contain fork(), but if there is a user-pro-
           vided fork(), that fork() is given precedence and  no  problem  ensues.
           The  situation is similar for environ: the definition in this volume of
           IEEE Std 1003.1-2001 is to be used if there is no user-provided environ
           to  take precedence.  At least three implementations are known to exist
           that solve this problem.
    
           E2BIG  The limit {ARG_MAX} applies not just to the size of the argument
                  list,  but  to  the  sum of that and the size of the environment
                  list.
    
           EFAULT Some historical systems return [EFAULT]  rather  than  [ENOEXEC]
                  when  the new process image file is corrupted. They are non-con-
                  forming.
    
           EINVAL This error condition was added to IEEE Std 1003.1-2001 to  allow
                  an  implementation to detect executable files generated for dif-
                  ferent architectures, and indicate this situation to the  appli-
                  cation. Historical implementations of shells, execvp(), and exe-
                  clp() that encounter an [ENOEXEC] error will execute a shell  on
                  the  assumption  that  the file is a shell script. This will not
                  produce the desired effect when the file is a  valid  executable
                  for  a  different architecture. An implementation may now choose
                  to avoid this problem by returning [EINVAL] when  a  valid  exe-
                  cutable  for  a different architecture is encountered. Some his-
                  torical implementations return [EINVAL]  to  indicate  that  the
                  path  argument contains a character with the high order bit set.
                  the  [ENAMETOOLONG]  error  condition could also be reached this
                  way.
    
           ETXTBSY
                  System V returns this error when the  executable  file  is  cur-
                  rently  open  for  writing  by  some  process.  This  volume  of
                  IEEE Std 1003.1-2001 neither requires nor prohibits this  behav-
                  ior.
    
           Other systems (such as System V) may return [EINTR] from exec.  This is
           not addressed by this volume of IEEE Std 1003.1-2001,  but  implementa-
           tions  may  have  a window between the call to exec and the time that a
           signal could cause one of the exec calls to return with [EINTR].
    
           An explicit statement  regarding  the  floating-point  environment  (as
           defined  in  the  <fenv.h>  header) was added to make it clear that the
           floating-point environment is set to its default when a call to one  of
           the  exec functions succeeds.  The requirements for inheritance or set-
           ting to the default for other process and thread start-up functions  is
           covered  by  more  generic  statements in their descriptions and can be
           summarized as follows:
    
           posix_spawn()
                  Set to default.
    
           fork() Inherit.
    
           pthread_create()
                  Inherit.
    
    
    

    FUTURE DIRECTIONS

           None.
    
    
    

    SEE ALSO

           alarm() , atexit() , chmod() , close() , exit() , fcntl()  ,  fork()  ,
           fstatvfs()  ,  getenv() , getitimer() , getrlimit() , mmap() , nice() ,
           posix_spawn() , posix_trace_eventid_open() ,  posix_trace_shutdown()  ,
           posix_trace_trid_eventid_open()  ,  putenv()  , semop() , setlocale() ,
           shmat() , sigaction() , sigaltstack() , sigpending() , sigprocmask()  ,
           system()  ,  times() , ulimit() , umask() , the Base Definitions volume
           of  IEEE Std 1003.1-2001,  Chapter  11,  General  Terminal   Interface,
           <unistd.h>
    
    
    

    COPYRIGHT

           Portions  of  this text are reprinted and reproduced in electronic form
           from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
           --  Portable  Operating  System  Interface (POSIX), The Open Group Base
           Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
           Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
           event of any discrepancy between this version and the original IEEE and
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz