Process.h

From Wikipedia, the free encyclopedia

process.h is a header file used in the C programming language that declares several useful library functions for running threads and processes from a program. Neither the header nor the library functions are defined by either the ISO C standard or by POSIX. They are not part of the C standard library. Most C compilers that target DOS, Windows 3.x, Phar Lap, DOSX, OS/2, or Win32 have this header and supply the concomitant library functions in the default C library. Most C compilers that target UNIX and Linux do not have this header and do not supply the concomitant library functions.

Contents

[edit] _beginthread

Prototype:

unsigned long _beginthread(void(* func)(void*), unsigned stack_size, void *arg);

Return value:

Returns the operating system handle of the newly created thread. If unsuccessful, the function returns -1 and sets errno.

This function creates a new thread of execution within the current process. Thread execution starts at the beginning of the function func. To terminate the thread correctly, func must call _endthread, freeing memory allocated by the run time library to support the thread.

The operating system allocates a stack for the thread containing the number of bytes specified by stack_size. If the value of stack_size is zero, the operating system creates a stack the same size as that of the main thread.[citation needed]

The operating system passes arg to func when execution begins. arg can be any 32-bit value cast to void*.

[edit] _c_exit, _cexit

Prototype:

void _c_exit(void);
void _cexit(void);

Return Value:

None

The _c_exit and _cexit functions perform cleanup operations and return without terminating the calling process. The _c_exit function performs a quick C library termination procedure and returns to the caller without processing registered exit functions (atexit or _onexit) or flushing buffers.

In contrast, the _cexit function performs a complete C library termination procedure by calling registered exit functions in LIFO order, flushing all I/ O buffers, and closing all open streams before returning to the caller.

Both functions restore interrupt vectors altered by the startup code.

[edit] _exec Functions

Prototypes:

int _execl(const char *path, const char *arg0,... const char *argn, NULL);
int _execle(const char *path, const char *arg0,... const char *argn, NULL, const char *const *envp);
int _execlp(const char *path, const char *arg0,... const char *argn, NULL);
int _execlpe(const char *path, const char *arg0,... const char *argn, NULL);
int _execv(const char *path, const char *const *argv);
int _execve(const char *path, const char *const *argv, const char *const *envp);
int _execvp(const char *path, const char *const *argv);
int _execvpe(const char *path, const char *const *argv, const char *const *envp);
  • Note: these functions can also be written without the preceding underscore (i.e. execl(...), execle(...), etc)

Return Value:

The _exec functions do not normally return to the calling process. If an exec function returns, an error occurred, the return value is -1, and errno is set to one of the following values:
E2BIG - The argument list exceeds the system limit.
EACCES - The specified file has a locking or sharing violation.
ENOENT - The file or path name not found.
ENOMEM - Not enough memory is available to execute the child process.

These functions load and execute a new child process by placing it in memory previously occupied by the calling process. Sufficient memory must be available.

Argument path specifies the path name of the file executed as a child process. arg0 through argn is a list of pointers to arguments to be passed to the child process. argv is an array of pointers to arguments. envp is an array of pointers to environment settings.

The base of each function is _exec, followed by one or more letters.

[edit] Letter Meaning

e - An array of pointers to environment arguments is explicitly passed to the child process.
l - Command line arguments are passed individually to the function.
p - Uses the PATH argument variable to find the file to be executed.
v - Command line arguments are passed to the function as an array of pointers.

Files open when an _exec call is made remain open in the new process. In the _execl, _execlp, _execv, and _execvp calls, the child process inherits the parent's environment. The _execle, _execlpe, _execve, and _execvpe calls alter the environment for the child process by passing a list of environment settings through the envp argument. This argument is an array of character pointers; each element (except for the final element) points to a null-terminated string defining an environment variable.

Each null-terminated string has the form

NAME= value

NAME is the environment variable name; value is the string value to which that variable is set. (value is not enclosed in double quotation marks.) The final element of the envp array must be NULL. When envp itself is NULL, the child process inherits the environment setttings of the parent process.

A program executed with one of the _exec functions is always loaded into memory as if the "maximum allocation" in the program's .exe file header is set to default value 0xFFFFH. You can use the EXEHDR utility to change the maximum allocation field of a program. However, if you do this and then invoke the program with one of the _exec functions, the program might behave differently from a program invoked directly from the operating-system command line or with one of the _spawn functions.

By checking the first two bytes of a file, command. com determines if the file is an .exe file or a .com file. The _exec functions can execute a file named by any extension, as long as its content is executable. You can also execute .bat files

The _exec calls do not preserve the translation modes of open files. If the child process uses files inherited from the parent, use the _setmode function to set the translation mode to the desired mode.

You must flush or close all open files before an _exec call.

[edit] _endthread

Prototype:

void _endthread (void);

Return Value:

None

The _endthread function terminates a thread created by _beginthread. Always call _endthread from within the thread function rather than just returning from the thread function; _enthread frees data structures created by _beginthread.

[edit] _getpid

Prototype:

int _getpid(void);
  • Note: can also be written without preceding underscore (i.e. getpid();)

Return Value:

Both functions return the process ID. There is no error return.

The _getpid function returns the process identification number (process ID) for the calling process. The ID uniquely identifies a process.

[edit] _spawn Functions

Prototype:

int _spawnl(int mode, char *filename, char *arg0,..., char *argn, NULL);
int _spawnle(int mode, char *filename, char *arg0,.., char *argn, NULL, char ** envp);
int _spawnlp(int mode, char *filename, char *arg0,..., char *argn, NULL);
int _spawnlpe(int mode, char *filename, char *arg0,..., char *argn, NULL, char ** envp);
int _spawnv(int mode, char *filename, char ** argv);
int _spawnve(int mode, char *filename, char ** argv, char ** envp);
int _spawnvp(int mode, char *filename, char ** argv);
int _spawnvpe(int mode, char *filename, char ** argv, char ** envp);
  • Note: these functions can also be written without the preceding underscore (i.e. spawnl(...), spawnlp(...), etc)

Return values:

The return value indicates the exit status of the spawned program. A value of 0 indicates that the spawned program executed successfully. A positive value indicates that the spawned program executed, but was aborted or ended in error, the value returned is the exit status of the child process. A negative value indicates that the spawned program did not execute, and errno is set.
Under Microsoft Windows, spawn returns the negated error code returned from LoadModule for compatibility with the C run-time library. The following error codes may be encountered:
-2 - File not found
-3 - Path not found
-11 - Invalid .exe file (for Windows)
-13 - DOS 4. 0 application
-14 - Unknown .exe type (may be DOS extended)

The _spawn functions load and execute a new child process. The current process may or may not continue to execute asynchronously. Creating a new subprocess requires enough memory in which both the child process and the current program can execute.

[edit] Mode values

The mode argument determines whether the child process runs asynchronously. Values for mode are:

_P_OVERLAY - Overlays parent process with child, which destroys the parent. This has the same effect as the _exec and exec functions.
_P_WAIT - Suspends parent process until the child process has finished executing.

The filename argument specifies the program to execute. For spawnlp and spawnvp only, if the filename does not have a path and is not in the current directory, the environment variable PATH determines which directories to search for the file. The string pointed to by argv[0] is the name of the program to run.

The command line passed to the spawned program is made up of the character strings, arg0 through argn, in the spawn call. The combined length of these strings must not exceed 128 characters. The argv argument is an array of character pointers. The last pointer in argv must be NULL to indicate the end of the list.

Files that are open when a spawn call is made remain open in the child process. In the _spawnl, _spawnlp, _spawnv, and _spawnvp calls, the child process inherits the environment of the parent. The _spawnle, _spawnlpe, _spawnve, and _spawnvpe calls allow the user to alter the child process's environment by passing a list of environment settings using the envp argument. This argument is an array of character pointers; each pointer (except for the last one) points to a null-terminated string defining an environment variable. An environment variable has the form

varname = value

where varname is the variable name and value is the string value (not enclosed in quotation marks.) The last pointer in the array is NULL. When the envp argument is null, the child inherits the parent's environment settings.

The _spawn functions can be used under Microsoft Windows. They use LoadModule to run the spawned process. If this fails an attempt is made to spawn a normal MS-DOS process. If a Windows application is spawned, the instance handle can be obtained using exec_instancehandleget.

It is possible to specify how the spawned programwill be shown using the functions _exec_showset, _exec_showget and _exec_showreset.

[edit] References

This article does not cite its references or sources.
Please help improve this article by introducing appropriate citations. (help, get involved!) This article has been tagged since December 2006.

    [edit] External links

    Retrieved from "http://en.wikipedia.org../../../p/r/o/Process.h.html"