| Previous | Contents | Index |
Provides users with a mechanism for multiplexing input/output over a set of file descriptors that reference open streams.
#include <poll.h>int poll (struct pollfd filedes [], nfds_t nfds, int timeout);
filedes
Points to an array of pollfd structures, one for each file descriptor of interest. Each pollfd structure includes the following members:int fd -- The file descriptor
int events -- The requested conditions
int revents -- The reported conditionsnfds
The number of pollfd structures in the filedes array.timeout
The maximum length of time (in milliseconds) to wait for at least one of the specified events to occur.
The poll function provides users with a mechanism for multiplexing input/output over a set of file descriptors that reference open streams. For each member of the array pointed to by filedes, poll examines the given file descriptor for the event(s) specified in events. The poll function identifies those streams on which an application can send or receive messages, or on which certain events have occurred.The filedes parameter specifies the file descriptor to be examined and the events of interest for each file descriptor. It is a pointer to an array of pollfd structures. The fd member of each pollfd structure specifies an open file descriptor. The poll function uses the events member to determine what conditions to report for this file descriptor. If one or more of these conditions is true, the poll function sets the associated revents member.
The events and revents members of each pollfd structure are bitmasks. The calling process sets the events bitmask, and poll sets the revents bitmasks. These bitmasks contain inclusive ORed combinations of condition options. The following condition options are defined:
POLLERR -- An error has occurred on the file descriptor. This option is only valid in the revents bitmask; it is not used in the events member.
For STREAMS devices, if an error occurs on the file descriptor and the device is also disconnected, poll returns POLLERR; POLLERR takes precedence over POLLHUP.
POLLHUP -- The device has been disconnected. This event is mutually exclusive with POLLOUT; a stream can never be writable if a hangup occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND or POLLPRI are not mutually exclusive. This option is only valid in the revents bitmask; it is ignored in the events member.
POLLIN -- Data other than high-priority data may be read without blocking. This option is set in revents even if the message is of zero length. In revents, this option is mutually exclusive with POLLPRI.
POLLNVAL -- The value specified for fd is invalid. This option is only valid in the revents member; it is ignored in the events member.
POLLOUT -- Normal (priority band equals 0) data may be written without blocking.
POLLPRI -- High-priority data may be received without blocking. This option is set in revents even if the message is of zero length. In revents, this option is mutually exclusive with POLLIN.
POLLRDBAND -- Data from a non-zero priority band may be read without blocking. This option is set in revents even if the message is of zero length.
POLLRDNORM -- Normal data (priority band equals 0) may be read without blocking. This option is set in revents even if the message is of zero length.
POLLWRBAND -- Priority data (priority band greater than 0) may be written. This event only examines bands that have been written to at least once.
POLLWRNORM -- Same as POLLOUT.The poll function ignores any pollfd structure whose fd member is less than 0 (zero). If the fd member of all pollfd structures is less than 0, the poll function will return 0 and have no other results.
The conditions indicated by POLLNORM and POLLOUT are true if and only if at least one byte of data can be read or written without blocking. There are two exceptions: regular files, which always poll true for POLLNORM and POLLOUT, and pipes, when the rules for the operation specify to return zero in order to indicate end-of-file.
The condition options POLLERR, POLLHUP, and POLLNVAL are always set in revents if the conditions they indicate are true for the specified file descriptor, whether or not these options are set in events.
For each call to the poll function, the set of reportable conditions for each file descriptor consists of those conditions that are always reported, together with any further conditions for which options are set in events. If any reportable condition is true for any file descriptor, the poll function will return with options set in revents for each true condition for that file descriptor.
If no reportable condition is true for any of the file descriptors, the poll function waits up to timeout milliseconds for a reportable condition to become true. If, in that time interval, a reportable condition becomes true for any of the file descriptors, poll reports the condition in the file descriptor's associated revents member and returns. If no reportable condition becomes true, poll returns without setting any revents bitmasks.
If the timeout parameter is a value of - 1, the poll function does not return until at least one specified event has occurred. If the value of the timeout parameter is 0 (zero), the poll function does not wait for an event to occur but returns immediately, even if no specified event has occurred.
The behavior of the poll function is not affected by whether the O_NONBLOCK option is set on any of the specified file descriptors.
The poll function supports regular files, terminal and pseudo-terminal devices, STREAMS-based files, FIFOs, and pipes. The behavior of poll on elements of file descriptors that refer to other types of files is unspecified.
For sockets, a file descriptor for a socket that is listening for connections indicates it is ready for reading after connections are available. A file descriptor for a socket that is connecting asynchronously indicates it is ready for writing after a connection is established.
n Upon successful completion, a nonnegative value is returned, indicating the number of file descriptors for which poll has set the revents bitmask. 0 poll has timed out and has not set any of the revents bitmasks. - 1 An error occurred. errno is set to indicate the error:
- EAGAIN -- Allocation of internal data structures failed. A later call to the poll function might complete successfully.
- EINTR -- A signal was caught during the poll function, and the signal handler was installed with an indication that functions are not to be restarted.
- EINVAL -- The nfds parameter is greater than OPEN_MAX, or one of the fd members refers to a stream or multiplexer that is linked (directly or indirectly) downstream from a multiplexer.
Initiates a pipe to a process.
#include <stdio.h>FILE *popen (const char *command, const char *type);
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:
- r ---the calling program can read from the standard output of the command by reading from the returned file stream.
- w ---the calling program can write to the standard input of the command by writing to the returned file stream.
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.The popen function uses the value of the DECC$PIPE_BUFFER_SIZE feature logical to set the buffer size of the mailbox it creates for the pipe. You can specify a DECC$PIPE_BUFFER_SIZE value of 512 to 65024 bytes. If DECC$PIPE_BUFFER_SIZE is not specified, the default buffer size of 512 is used.
See also fflush , pclose , and setvbuf .
x A pointer to the FILE structure for the opened stream. NULL Indicates an error. Unable to create files or processes.
Returns the first argument raised to the power of the second argument.
#include <math.h>double pow (double x, double y);
float powf (float x, float y); (ALPHA, I64)
long double powl (long double x, long double y); (ALPHA, I64)
x
A floating-point base to be raised to an exponent y.y
The exponent to which the base x is to be raised.
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 ERANGE or EDOM.
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 ERANGE or EDOM.
#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
Reads bytes from a given position within a file without changing the file pointer.
#include <unistd.h>ssize_t pread (int file_desc, void *buffer, size_t nbytes, off_t offset);
file_desc
A file descriptor that refers to a file currently opened for reading.buffer
The address of contiguous storage in which the input data is placed.nbytes
The maximum number of bytes involved in the read operation.offset
The offset for the desired position inside the file.
The pread function performs the same action as read , except that it reads from a given position in the file without changing the file pointer. The first three arguments to pread are the same as for read , with the addition of a fourth argument offset for the desired position inside the file. An attempt to perform a pread on a file that is incapable of seeking results in an error.
n The number of bytes read. - 1 Upon failure, the file pointer remains unchanged and pread sets errno to one of the following values:
- EINVAL -- The offset argument is invalid. The value is negative.
- EOVERFLOW -- The file is a regular file, and an attempt was made to read or write at or beyond the offset maximum associated with the file.
- ENXIO -- A request was outside the capabilities of the device.
- ESPIPE -- fildes is associated with a pipe or FIFO.
Performs formatted output from the standard output ( stdout ). See Chapter 2 for information on format specifiers.
#include <stdio.h>int printf (const char *format_spec, ...);
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.
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 .
Perform a printf in the specified window, starting at the current position of the cursor. The printw function acts on the stdscr window.
#include <curses.h>printw (char *format_spec, ...);
int wprintw (WINDOW *win, char *format_spec, ...);
win
A pointer to the window.format_spec
A pointer to the format specification string....
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.
The formatting specification (format_spec) and the other arguments are identical to those used with the printf function.The printw and wprintw functions format and then print the resultant string to the window using the addstr function. For more information, see the printf and scrollok functions in this section. See Chapter 2 for information on format specifiers.
OK Indicates success. ERR Indicates that the function makes the window scroll illegally.
The putc macro writes a single character to a specified file.
#include <stdio.h>int putc (int character, FILE *file_ptr);
character
The character to be written.file_ptr
A file pointer to the output stream.
The putc macro writes the byte character (converted to an unsigned char) to the output specified by the file_ptr parameter. The byte is written at the position at which the file pointer is currently pointing (if defined) and advances the indicator appropriately. If the file cannot support positioning requests, or if the output stream was opened with append mode, the byte is appended to the output stream.Since putc is a macro, a file pointer argument with side effects (for example, putc (ch, *f++) ) might be evaluated incorrectly. In such a case, use the fputc function instead.
Compiling with the __UNIX_PUTC macro defined enables an optimization that uses a faster, inlined version of this function.
See also putc_unlocked .
x The character written to the file. Indicates success. EOF Indicates output errors.
Same as putc , except used only within a scope protected by flockfile and funlockfile .
#include <stdio.h>int putc_unlocked (int character, FILE *file_ptr);
character
The character to be written.file_ptr
A file pointer to the output stream.
The reentrant version of the putc macro is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the stream. The unlocked version of this call, putc_unlocked can be used to avoid the overhead. The putc_unlocked macro is functionally identical to the putc macro, except that it is not required to be implemented in a thread-safe manner. The putc_unlocked macro can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before putc_unlocked is used.Since putc_unlocked is a macro, a file pointer argument with side effects might be evaluated incorrectly. In such a case, use the fputc_unlocked function instead.
Compiling with the __UNIX_PUTC macro defined enables an optimization that uses a faster, inlined version of this function.
See also flockfile , ftrylockfile , and funlockfile .
x The character written to the file. Indicates success. EOF Indicates the end-of-file or an error.
| Previous | Next | Contents | Index |