Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

pathconf

Retrieves file implementation characteristics.

Format

#include <unistd.h>

long int pathconf (const char *path, int name);

Arguments

path

The pathname of a file or directory.

name

The configuration attribute to query. If this attribute is not applicable to the file specified by the path argument, the pathconf function returns an error.

Description

The pathconf function allows an application to determine the characteristics of operations supported by the file system underlying the file named by path. Read, write, or execute permission of the named file is not required, but you must be able to search all directories in the path leading to the file.

Symbolic values for the name argument are defined in the <unistd.h> header file, as follows:
_PC_LINK_MAX The maximum number of links to the file. If the path argument refers to a directory, the value returned applies to the directory itself.
_PC_MAX_CANON The maximum number of bytes in a canonical input line. This is applicable only to terminal devices.
_PC_MAX_INPUT The number of types allowed in an input queue. This is applicable only to terminal devices.
_PC_NAME_MAX Maximum number of bytes in a file name (not including a terminating null). The byte range value is between 13 and 255. This is applicable only to a directory file. The value returned applies to file names within the directory.
_PC_PATH_MAX Maximum number of bytes in a path name (not including a terminating null). The value is never larger than 65,535. This is applicable only to a directory file. The value returned is the maximum length of a relative pathname when the specified directory is the working directory.
_PC_PIPE_BUF Maximum number of bytes guaranteed to be written atomically. This is applicable only to a FIFO. The value returned applies to the referenced object. If the path argument refers to a directory, the value returned applies to any FIFO that exists or can be created within the directory.
_PC_CHOWN_RESTRICTED This is applicable only to a directory file. The value returned applies to any files (other than directories) that exist or can be created within the directory.
_PC_NO_TRUNC Returns 1 if supplying a component name longer than allowed by NAME_MAX causes an error. Returns 0 (zero) if long component names are truncated. This is applicable only to a directory file.
_PC_VDISABLE This is always 0 (zero); no disabling character is defined. This is applicable only to a terminal device.

Return Values

x Resultant value of the configuration attribute specified in name.
- 1 Indicates an error; errno is set to one of the following values:
  • EACCES -- Search permission is denied for a component of the path prefix.
  • EINVAL -- The name argument specifies an unknown or inapplicable characteristic.
  • EFAULT -- The path argument is an invalid address.
  • ENAMETOOLONG -- The length of the path string exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
  • ENOENT -- The named file does not exist or the path argument points to an empty string.
  • ENOTDI -- A component of the path prefix is not a directory.

pause

Suspends the calling process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.

Format

#include <unistd.h>

int pause (void);

Description

The pause function suspends the calling process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.

If the action is to terminate the process, pause does not return.

If the action is to execute a signal-catching function, pause returns after the signal-catching function returns.

Return Value

  Since the pause function suspends process execution indefinitely unless interrupted by a signal, there is no successful completion return value.
- 1 In cases where pause returns, the return value is - 1, and errno is set to EINTR.

pclose

Closes a pipe to a process.

Format

#include <stdio.h>

int pclose (FILE *stream);

Arguments

stream

A pointer to a FILE structure for an open pipe returned by a previous call to the popen function.

Description

The pclose function closes a pipe between the calling program and a shell command to be executed. Use pclose to close any stream you have opened with popen . The pclose function waits for the associated process to end, and then returns the exit status of the command. See the description of waitpid for information on interpreting the exit status.

Beginning with OpenVMS Version 7.3-1, when compiled with the _VMS_WAIT macro defined, the pclose function returns the OpenVMS completion code of the child process.

See also popen in this section.

Return Values

x Exit status of child.
- 1 Indicates an error. The stream argument is not associated with a popen function. errno is set to one of the following:
  • ECHILD -- cannot obtain the status of the child process.

perror

Writes a short error message to stderr describing the current value of errno .

Format

#include <stdio.h>

void perror (const char *str);

Argument

str

Usually the name of the program that caused the error.

Description

The perror function uses the error number in the external variable errno to retrieve the appropriate locale-dependent error message. The function writes out the message as follows: str (a user-supplied prefix to the error message), followed by a colon and a space, followed by the message itself, followed by a new-line character.

See the description of errno in Chapter 4 for a list of possible errors.

See also strerror in this section.

Example


#include <stdio.h> 
#include <stdlib.h> 
 
main(argc, argv) 
    int argc; 
    char *argv[]; 
{ 
    FILE *fp; 
 
    fp = fopen(argv[1], "r");   /* Open an input file. */ 
    if (fp == NULL) { 
 
        /* If the fopen call failed, perror prints out a        */ 
        /* diagnostic:                                          */ 
        /*                                                      */ 
        /*  "open: <error message>"                             */ 
        /*  This error message provides a diagnostic explaining */ 
        /*  the cause of the failure.                           */ 
 
        perror("open"); 
        exit(EXIT_FAILURE); 
    } 
    else 
        fclose(fd) ; 
}

pipe

Creates a temporary mailbox that can be used to read and write data between a parent and child process. The channels through which the processes communicate are called a pipe.

Format

#include <unistd.h>

int pipe (int array_fdscptr[2]); (ISO POSIX-1)

int pipe (int array_fdscptr[2], ...); (COMPAQ C EXTENSION)

Arguments

array_fdscptr

An array of file descriptors. A pipe is implemented as an array of file descriptors associated with a mailbox. These mailbox descriptors are special in that these are the only file descriptors which, when passed to the isapipe function, will return 1.

The file descriptors are allocated in the following way:

...

Represents two optional, positional arguments, flag and bufsize, which follow:

flag

An optional argument used as a bitmask.

If either the O_NDELAY or O_NONBLOCK bit is set, the I/O operations to the mailbox through array_fdscptr file descriptors terminate immediately, rather than waiting for another process.

If, for example, the O_NDELAY bit is set and the child issues a read request to the mailbox before the parent has put any data into it, the read terminates immediately with zero status. If neither the O_NDELAY nor O_NONBLOCK bit is set, the child will be waiting on the read until the parent writes any data into the mailbox. This is the default behavior if no flag argument is specified.

The values of O_NDELAY and O_NONBLOCK are defined in the <fcntl.h> header file. Any other bits in the flag argument are ignored. You must specify this argument if the second optional, positional argument bufsize is specified. If the flag argument is needed only to allow specification of the bufsize argument, specify flag as zero.

bufsize

Optional argument of type int that specifies the size of the mailbox, in bytes. If you do not specify this argument, Compaq C for OpenVMS Systems creates a mailbox with a default size of 512 bytes.

If you do specify this argument, be sure to precede it with a flag argument of 0.

Description

The mailbox used for the pipe is a temporary mailbox. The mailbox is not deleted until all processes that have open channels to that mailbox close those channels. The last process that closes a pipe writes a message to the mailbox, indicating the end-of-file.

The mailbox is created by using the $CREMBX system service, specifying the following characteristics:

The buffer quota of 512 characters implies that you cannot write more than 512 characters to the mailbox before all or part of the mailbox is read. Since a mailbox record is slightly larger than the data part of the message that it contains, not all of the 512 characters can be used for message data. You can increase the size of the buffer by specifying an alternative size using the optional, third argument to the pipe function. A pipe under the OpenVMS system is a stream-oriented file with no carriage-control attributes. It is fully buffered by default in the Compaq C RTL. A mailbox used as a pipe is different than a mailbox created by the application. A mailbox created by the application defaults to a record-oriented file with carriage return, carriage control. Additionally, writing a zero-length record to a mailbox writes an EOF, as does each close of the mailbox. For a pipe, only the last close of a pipe writes an EOF.

The pipe is created by the parent process before vfork and an exec function are called. By calling pipe first, the child inherits the open file descriptors for the pipe. You can then use the getname function to return the name of the mailbox associated with the pipe, if this information is desired. The mailbox name returned by getname has the format _MBAnnnn:, where nnnn is a unique number.

Both the parent and the child need to know in advance which file descriptors will be allocated for the pipe. This information cannot be retrieved at run time. Therefore, it is important to understand how file descriptors are used in any Compaq C for OpenVMS program. For more information about file descriptors, see Chapter 2.

File descriptors 0, 1, and 2 are open in a Compaq C for OpenVMS program for stdin (SYS$INPUT), stdout (SYS$OUTPUT), and stderr (SYS$ERROR), respectively. Therefore, if no other files are open when pipe is called, pipe assigns file descriptor 3 for writing and file descriptor 4 for reading. In the array returned by pipe , 4 is placed in element 0 and 3 is placed in element 1.

If other files have been opened, pipe assigns the first available file descriptor for writing and the next available file descriptor for reading. In this case, the pipe does not necessarily use adjacent file descriptors. For example, assume that two files have been opened and assigned to file descriptors 3 and 4 and the first file is then closed. If pipe is called at this point, file descriptor 3 is assigned for writing and file descriptor 5 is assigned for reading. Element 0 of the array will contain 5 and element 1 will contain 3.

In large applications that do large amounts of I/O, it gets more difficult to predict which file descriptors are going to be assigned to a pipe; and, unless the child knows which file descriptors are being used, it will not be able to read and write successfully from and to the pipe.

One way to be sure that the correct file descriptors are being used is to use the following procedure:

  1. Choose two descriptor numbers that will be known to both the parent and the child. The numbers should be high enough to account for any I/O that might be done before the pipe is created.
  2. Call pipe in the parent at some point before calling an exec function.
  3. In the parent, use dup2 to assign the file descriptors returned by pipe to the file descriptors you chose. This now reserves those file descriptors for the pipe; any subsequent I/O will not interfere with the pipe.

You can read and write through the pipe using the UNIX I/O functions read and write , specifying the appropriate file descriptors. As an alternative, you can issue fdopen calls to associate file pointers with these file descriptors so that you can use the Standard I/O functions ( fread and fwrite ).

Two separate file descriptors are used for reading from and writing to the pipe, but only one mailbox is used so some I/O synchronization is required. For example, assume that the parent writes a message to the pipe. If the parent is the first process to read from the pipe, then it will read its own message back as shown in Figure REF-1.

Figure REF-1 Reading and Writing to a Pipe

Return Values

0 Indicates success.
- 1 Indicates an error.

popen

Initiates a pipe to a process.

Format

#include <stdio.h>

FILE *popen (const char *command, const char *type);

Arguments

command

A pointer to a null-terminated string containing a shell command line.

type

A pointer to a null-terminated string containing an I/O mode. Because open files are shared, you can use a type r command as an input filter and a type w command as an output filter. Specify one of the following values for the type argument:

Description

The popen function creates a pipe between the calling program and a shell command awaiting execution. It returns a pointer to a FILE structure for the stream.

Note
When you use the popen function to invoke an output filter, beware of possible deadlock caused by output data remaining in the program buffer. You can avoid this by either using the setvbuf function to ensure that the output stream is unbuffered, or the fflush function to ensure that all buffered data is flushed before calling the pclose function.

See also fflush , pclose , and setvbuf in this section.

Return Values

x A pointer to the FILE structure for the opened stream.
NULL Indicates an error. Unable to create files or processes.

pow

Returns the first argument raised to the power of the second argument.

Format

#include <math.h>

double pow (double x, double y);

float powf (float x, float y); (ALPHA ONLY)

long double powl (long double x, long double y); (ALPHA ONLY)

Arguments

x

A floating-point base to be raised to an exponent y.

y

The exponent to which the base x is to be raised.

Description

The pow functions raise a floating-point base x to a floating-point exponent y. The value of pow (x,y) is computed as e**(y ln(x)) for positive x.

If x is 0 and y is negative, - HUGE_VAL is returned, and errno is set to EDOM.

Return Values

x The result of the first argument raised to the power of the second.
1.0 The base is 0 and the exponent is 0.
HUGE_VAL The result overflowed; errno is set to ERANGE.
- HUGE_VAL The base is 0 and the exponent is negative; errno is set to EDOM.

Example


#include <stdio.h> 
#include <math.h> 
#include <errno.h> 
 
main() 
{ 
    double x; 
 
    errno = 0; 
 
    x = pow(-3.0, 2.0); 
    printf("%d, %f\n", errno, x); 
}

This example program outputs the following: 


0, 9.000000

printf

Performs formatted output from the standard output ( stdout ). See Chapter 2 for information on format specifiers.

Format

#include <stdio.h>

int printf (const char *format_spec, ...);

Arguments

format_spec

Characters to be written literally to the output or converted as specified in the ... arguments.

...

Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

If no conversion specifications are given, you may omit the output sources. Otherwise, the function call must have exactly as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.

Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.

Return Values

x The number of bytes written.
Negative value Indicates that an output error occurred. The function sets errno . For a list of errno values set by this function, see fprintf in this section.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5763PRO_043.HTML