United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# wait4

> Waits for a child process to stop or terminate.

## Format

> #include <wait.h>

> pid_t wait4 (pid_t process_id, union wait *status_location, int options, struct rusage *resource_usage);

## Arguments

> ### status_location

> A pointer to a location that contains the termination status of the child process as defined in the `<wait.h>` header file.

> Beginning with OpenVMS Version 7.2, when compiled with the _VMS_WAIT macro defined, this function puts the OpenVMS completion code of the child process at the address specified in the status_location argument.

> ### process_id

> The child process or set of child processes.

> ### options

> Flags that modify the behavior of the function. These flags are defined in the Description section.

> ### resource_usage

> The location of a structure that contains the resource utilization information for terminated child processes.

## Description

> This function suspends the calling process until the request is completed.

> The process_id argument allows the calling process to gather status from a specific set of child processes, according to the following rules:

> If the process_id is | Then status is requested
> --- | ---
> Equal to --1 | For any child process. In this respect, the `waitpid` function is equivalent to the `wait` function.
> Greater than 0 | For a single child process and specifies the process ID.

> The `wait4` function only returns the status of a child process from this set.

> The options argument to the `wait4` function modifies the behavior of the function. You can combine the flags for the options argument by specifying their bitwise-inclusive OR. The flags are:

> WNOWAIT | Specifies that the process whose status is returned in status_location is kept in a waitable state. You can wait for the process again with the same results.
> WNOHANG | Prevents the suspension of the calling process. If there are child processes that stopped or terminated, one is chosen and the `waitpid` function returns its process ID, as when you do not specify the WNOHANG flag. If there are no terminated processes (that is, if `waitpid` suspends the calling process without the WNOHANG flag), 0 is returned. Because you can never wait for process 0, there is no confusion arising from this return.
> WUNTRACED | Specifies that the call return additional information when the child processes of the current process stop because the child process received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.

> If the `wait4` function returns because the status of a child process is available, the process ID of the child process is returned. Information is stored in the location pointed to by status_location, if this pointer is not null.

> The value stored in the location pointed to by status_location is 0 only if the status is returned from a terminated child process that did one of the following:

> - Returned 0 from the `main` function.
> - Passed 0 as the status argument to the `_exit` or `exit` function.

> Regardless of the status_location value, you can define this information using the macros defined in the `<wait.h>` header file, which evaluate to integral expressions. In the following macro descriptions, status_value is equal to the integer value pointed to by status_location:

> `WIFEXITED` (status_value ) | Evaluates to a nonzero value if status was returned for a child process that terminated normally.
> `WEXITSTATUS` (status_value ) | If the value of `WIFEXITED` (status_value ) is nonzero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to the `_exit` or `exit` function, or to the value the child process returned from the `main` function.
> `WIFSIGNALED` (status_value ) | Evaluates to nonzero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught.
> `WTERMSIG` (status_value ) | If the value of `WIFSIGNALED` (status_value ) is nonzero, this macro evaluates to the number of the signal that caused the termination of the child process.
> `WIFSTOPPED` (status_value ) | Evaluates to a nonzero value if status was returned for a child process that is currently stopped.
> `WSTOPSIG` (status_value ) | If the value of `WIFSTOPPED` (status_value ) is nonzero, this macro evaluates to the number of the signal that caused the child process to stop.
> `WIFCONTINUED` (status_value ) | Evaluates to a nonzero value if status was returned for a child process that has continued.

> If the information stored at the location pointed to by status_location was stored there by a call to `wait4` that specified the `WUNTRACED` flag, one of the following macros evaluates to a nonzero value:

> - `WIFEXITED` (*status_value)
> - `WIFSIGNALED` (*status_value)
> - `WIFSTOPPED` (*status_value)
> - `WIFCONTINUED` (*status_value)

> If the information stored in the location pointed to by status_location resulted from a call to `wait4` without the `WUNTRACED` flag specified, one of the following macros evaluates to a nonzero value:

> - `WIFEXITED` (*status_value)
> - `WIFSIGNALED` (*status_value)

> The `wait4` function is similar to the `wait3` function. However, the `wait4` function waits for a specific child as indicated by the process_id argument. The resource_usage argument points to a location that contains resource usage information for the child processes as defined in the `<resource.h>` header file.

> See also `exit` and `_exit` in this section.

## Return Values

> 0 | Indicates success. There are no stopped or exited child processes, the WNOHANG option is specified.
> x | The process_id of the child process. Status of a child process is available.
> --1 | Indicates an error; `errno` is set to one of the following values: ECHILD -- There are no child processes to wait for. EINTR -- Terminated by receipt of a signal caught by the calling process. EFAULT -- The status_location or resource_usage argument points to a location outside of the address space of the process. EINVAL--- The value of the options argument is not valid.

# waitpid

> Waits for a child process to stop or terminate.

## Format

> #include <wait.h>

> pid_t waitpid (pid_t process_id, int *status_location, int options);

## Arguments

> ### process_id

> The child process or set of child processes.

> ### status_location

> A pointer to a location that contains the termination status of the child process as defined in the `<wait.h>` header file.

> Beginning with OpenVMS Version 7.2, when compiled with the _VMS_WAIT macro defined, this function puts the OpenVMS completion code of the child process at the address specified in the status_location argument.

> ### options

> Flags that modify the behavior of the function. These flags are defined in the Description section.

## Description

> This function suspends the calling process until the request is completed. It is redefined so that only the calling thread is suspended.

> If the process_id argument is --1 and the options argument is 0, the `waitpid` function behaves the same as the `wait` function. If these arguments have other values, the `waitpid` function is changed as specified by those values.

> The process_id argument allows the calling process to gather status from a specific set of child processes, according to the following rules:

> If the process_id is | Then status is requested
> --- | ---
> Equal to --1 | For any child process. In this respect, the `waitpid` function is equivalent to the `wait` function.
> Greater than 0 | For a single child process and specifies the process ID.

> The `waitpid` function only returns the status of a child process from this set.

> The options argument to the `waitpid` function modifies the behavior of the function. You can combine the flags for the options argument by specifying their bitwise-inclusive OR. The flags are:

> WCONTINUED | Specifies that the following is reported to the calling process: the status of any continued child process specified by the process_id argument whose status is unreported since it continued.
> WNOWAIT | Specifies that the process whose status is returned in status_location is kept in a waitable state. You can wait for the process again with the same results.
> WNOHANG | Prevents the calling process from being suspended. If there are child processes that stopped or terminated, one is chosen and `waitpid` returns its pid, as when you do not specify the WNOHANG flag. If there are no terminated processes (that is, if `waitpid` suspends the calling process without the WNOHANG flag), 0 (zero) is returned. Because you can never wait for process 0, there is no confusion arising from this return.
> WUNTRACED | Specifies that the call return additional information when the child processes of the current process stop because the child process received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP signal.

> If the `waitpid` function returns because the status of a child process is available, the process ID of the child process is returned. Information is stored in the location pointed to by status_location, if this pointer is not null. The value stored in the location pointed to by status_location is 0 only if the status is returned from a terminated child process that did one of the following:

> - Returned 0 from the `main` function.
> - Passed 0 as the status argument to the `_exit` or `exit` function.

> Regardless of the value of status_location, you can define this information using the macros defined in the `<wait.h>` header file, which evaluate to integral expressions. In the following function descriptions, status_value is equal to the integer value pointed to by status_location:

> `WIFEXITED` (status_value ) | Evaluates to a nonzero value if status was returned for a child process that terminated normally.
> `WEXITSTATUS` (status_value ) | If the value of `WIFEXITED` (status_value ) is nonzero, this macro evaluates to the low-order 8 bits of the status argument that the child process passed to the `_exit` or `exit` function, or to the value the child process returned from the `main` function.
> `WIFSIGNALED` (status_value ) | Evaluates to nonzero value if status returned for a child process that terminated due to the receipt of a signal not caught.
> `WTERMSIG` (status_value ) | If the value of `WIFSIGNALED` (status_value ) is nonzero, this macro evaluates to the number of the signal that caused the termination of the child process.
> `WIFSTOPPED` (status_value ) | Evaluates to a nonzero value if status was returned for a child process that is currently stopped.
> `WSTOPSIG` (status_value ) | If the value of `WIFSTOPPED` (status_value ) is nonzero, this macro evaluates to the number of the signal that caused the child process to stop.
> `WIFCONTINUED` (status_value ) | Evaluates to a nonzero value if status returned for a child process that continued.

> If the information stored at the location pointed to by status_location is stored there by a call to `waitpid` that specified the `WUNTRACED` flag, one of the following macros evaluates to a nonzero value:

> - `WIFEXITED` (*status_value)
> - `WIFSIGNALED` (*status_value)
> - `WIFSTOPPED` (*status_value)
> - `WIFCONTINUED` (*status_value)

> If the information stored in the buffer pointed to by status_location resulted from a call to `waitpid` without the `WUNTRACED` flag specified, one of the following macros evaluates to a nonzero value:

> - `WIFEXITED` (*status_value)
> - `WIFSIGNALED` (*status_value)

> If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes is assigned a parent process ID equal to the process ID of the init process.

> See also `exit` , `_exit` , and `wait` in this section.

## Return Values

> 0 | Indicates success. If the `WNOHANG` option was specified, and there are no stopped or exited child processes, the `waitpid` function also returns a value of 0.
> --1 | Indicates an error; `errno` is set to one of the following values: ECHILD---The calling process has no existing unwaited-for child processes. The process or process group ID specified by the process_id argument does not exist or is not a child process of the calling process. EINTR---The function was terminated by receipt of a signal. If the `waitpid` function returns because the status of a child process is available, the process ID of the child is returned to the calling process. If they return because a signal was caught by the calling process, --1 is returned. EFAULT--- The status_location argument points to a location outside of the address space of the process. EINVAL--- The value of the options argument is not valid.

# wcrtomb

> Converts the wide character to its multibyte character representation.

## Format

> #include <wchar.h>

> size_t wcrtomb (char *s, wchar_t wc, mbstate_t *ps);

## Arguments

> ### s

> A pointer to the resulting multibyte character.

> ### wc

> A wide character.

> ### ps

> A pointer to the `mbstate_t` object. If a NULL pointer is specified, the function uses its internal `mbstate_t` object. `mbstate_t` is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

## Description

> If s is a NULL pointer, the `wcrtomb` function is equivalent to the call:

>        wcrtomb (buf, L'\0', ps)

> where buf is an internal buffer.

> If s is not a NULL pointer, the `wcrtomb` function determines the number of bytes needed to represent the multibyte character that corresponds to the wide character specified by wc (including any shift sequences), and stores the resulting bytes in the array whose first element is pointed to by s. At most `MB_CUR_MAX` bytes are stored.

> If wc is a null wide character, a null byte is stored preceded by any shift sequence needed to restore the initial shift state. The resulting state described is the initial conversion state.

## Return Values

> n | The number of bytes stored in the resulting array, including any shift sequences to represent the multibyte character.
> --1 | Indicates an encoding error. The wc argument is not a valid wide character. The global `errno` is set to `EILSEQ` ; the conversion state is undefined.

# wcscat

> Concatenates two wide-character strings.

## Format

> #include <wchar.h>

> wchar_t *wcscat (wchar_t *wstr_1, const wchar_t *wstr_2);

Function Variants This function also has variants named `_wcscat32` and `_wcscat64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### wstr_1, wstr_2

> Pointers to null-terminated wide-character strings.

## Description

> This function appends the wide-character string wstr_2, including the terminating null character, to the end of wstr_1. See also `wcsncat` in this section.

## Return Values

> x | The first argument, wstr_1, which is assumed to be large enough to hold the concatenated result.

## Example

>     #include <stdlib.h>
>     #include <stdio.h>
>     #include <wchar.h>
>     #include <string.h>

>     /* This program concatenates two wide-character strings using   */
>     /* the wcscat function, and then manually compares the result   */
>     /* to the expected result                                       */

>     #define S1LENGTH 10
>     #define S2LENGTH 8

>     main()
>     {
>         int i;
>         wchar_t s1buf[S1LENGTH + S2LENGTH];
>         wchar_t s2buf[S2LENGTH];
>         wchar_t test1[S1LENGTH + S2LENGTH];

>         /* Initialize the three wide-character strings */

>         if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == (size_t)-1) {

>             perror("mbstowcs");
>             exit(EXIT_FAILURE);
>         }

>         if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size_t)-1) {

>             perror("mbstowcs");
>             exit(EXIT_FAILURE);
>         }

>         if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH + S2LENGTH)

>             == (size_t)-1) {

>             perror("mbstowcs");
>             exit(EXIT_FAILURE);
>         }

>         /* Concatenate s1buf with s2buf, placing the result into */
>         /* s1buf.  Then compare s1buf with the expected result   */
>         /* in test1.                                             */

>         wcscat(s1buf, s2buf);

>         for (i = 0; i < S1LENGTH + S2LENGTH - 2; i++) {
>             /* Check that each character is correct */
>             if (test1[i] != s1buf[i]) {
>                 printf("Error in wcscat\n");
>                 exit(EXIT_FAILURE);
>             }
>         }

>         printf("Concatenated string: <%S>\n", s1buf);
>     }

> Running the example produces the following result:

>     Concatenated string: <abcmnexyz orthis>

Previous | Next | Contents | Index

privacy and legal statement