Streams API

The streams layer is easily the largest piece of PHP's core API. To help navigate through the sheer volume of method calls, this section of the appendix will attempt to break them down into functional groupings covering creation, access, manipulation, and destruction.

Stream Creation and Destruction

php_stream *php_stream_alloc(php_stream_ops *ops, void *abstract, const char *persistent_id, const char *mode);

Allocates a PHP Stream instance associated with the identified stream ops. This method is typically used by stream or wrapper implementations; refer to Chapter 15.

int php_stream_from_persistent_id(const char *persistent_id, php_stream **stream TSRMLS_DC);

Recovers a stream instance based on its persistent ID (as provided to php_stream_alloc().

int php_stream_free(php_stream *stream, int close_options); int php_stream_close(php_stream *stream); int php_stream_pclose(php_stream *stream);

Closes a stream and free the resources associated with it. close_options can be any combination of the following flags. php_stream_close() calls php_stream_free() with close_options set to PHP_STREAM_FREE_CLOSE, while php_stream_pclose() calls it with PHP_STREAM_FREE_CLOSE_PERSISTENT.

php_stream_wrapper *php_stream_locate_url_wrapper(const char *path, char **path_for_open, int options TSRMLS_DC);

Retrieves the currently registered wrapper struct associated with a given URI. Typically path_for_open will simply be populated with the value of path; however, when filebased URIs are given, the leading file:// scheme identifier will be automatically stripped so that calls to the underlying open() syscall will function normally.

php_stream *php_stream_open_wrapper(char *path, char *mode, int options, char **opened_path); php_stream *php_stream_open_wrapper_ex(char *path, char *mode, int options, char **opened_path, php_stream_context *context); FILE *php_stream_open_wrapper_as_file(char *path, char *mode, int options, char **opened_path);

Creates a stream instance or stdio file pointer from the given path. The php_stream_open_wrapper() variant functions identically to the extended version with a value of NULL passed for context. If php_stream_open_wrapper_as_file() is called for a protocol that does not support casting to FILE*, the streams layer will raise an error, close the intermediate stream, and return NULL.

Stream I/O

size_t php_stream_read(php_stream *stream, char *buf, size_t maxlen); char *php_stream_get_record(php_stream *stream, size_t maxlen, size_t *returned_len, char *delim, size_t delim_len TSRMLS_DC); char *php_stream_get_line(php_stream *stream, char *buf, size_t maxlen, size_t *returned_len); char *php_stream_gets(php_stream *stream, char *buf, size_t maxlen); int php_stream_getc(php_stream *stream);

Reads data from a stream instance. php_stream_read() reads raw bytes with no regard to their content and only attempts one read call to the underlying transport. This means that, depending on the underlying implementation's semantics, fewer than maxlen bytes can be returned even if more data is currently available. Conversely, the three line-oriented data retrieval operations (get_record, get_line, and gets) perform a greedy read, buffering up as much of the stream's data as necessary to either locate an end of line sequence, or fill the provided buffer to maxlen bytes. php_stream_getc() will read a single byte from the stream.

size_t php_stream_write(php_stream *stream, const char *buf, size_t count) size_t php_stream_write_string(php_stream *stream, const char *buf); int php_stream_puts(php_stream *stream, char *buf); size_t php_stream_printf(php_stream *stream TSRMLS_DC, const char *fmt, ...); int php_stream_putc(php_stream *stream, int c);

Writes data to a stream instance. php_stream_puts() differs from php_stream_write() by appending an additional newline character after writing the contents of buf. The putc and puts varieties return 1 on success or 0 on failure while the remaining versions return the number of bytes actually written on the streamwhich may be fewer that the number of bytes requested to write.

int php_stream_eof(php_stream *stream);

Returns a nonzero value if the stream's file pointer has reached the end of file.

int php_stream_flush(php_stream *stream, int closing);

Instructs the underlying stream implementation to flush any internally buffered data to the target resource.

size_t php_stream_copy_to_stream(php_stream *src, php_stream *dest, size_t maxlen);

Reads remaining contentup to maxlen bytesfrom src stream and write it out to dest stream.

size_t php_stream_copy_to_mem(php_stream *src, char **buffer, size_t maxlen, int persistent);

Reads remaining contentup to maxlen bytesfrom src stream and place it into a newly allocated buffer. If persistent is nonzero, permanent memory allocators will be used; otherwise, non-persistent memory will be allocated for buffer.

size_t php_stream_passthru(php_stream * src);

Reads remaining content from src stream and output it to the browser, command line, or other appropriate target.

char *php_stream_mmap_range(php_stream *stream, size_t offset, size_t length, php_stream_mmap_operation_t mode, size_t *mapped_len); int php_stream_mmap_unmap(php_stream *stream TSRMLS_DC); int php_stream_mmap_supported(php_stream *stream); int php_stream_mmap_possible(php_stream *stream);

Maps or unmaps a portion of a stream's contents to memory. Note that PHP imposes an artificial limit of 2MB on memory mapping operations. The functions returning integers yield zero for failure or to indicate a negative response, or nonzero otherwise. php_stream_mmap_range() returns a pointer to the mem-mapped range on success, or NULL on failure.

Stream Manipulation

int php_stream_seek(php_stream *stream, off_t offset, int whence); int php_stream_rewind(php_stream *stream); off_t php_stream_tell(php_stream *stream);

Moves the file pointer within a seekable stream (seek) or report its current position (tell). php_stream_rewind() is provided as a convenience macro mapping to php_stream_seek(stream,0, SEEK_SET);.

int php_stream_stat(php_stream *stream, php_stream_statbuf *ssb); int php_stream_stat_path(char *path, int flags, php_stream_statbuf *ssb, php_stream_context *context);

Reports fstat() or stat() style information from an open stream or URI path respectively.

int php_stream_set_option(php_stream *stream, int option, int value, void *ptrparam); int php_stream_truncate_set_size(php_stream *stream, size_t newsize);

Performs an ioctl() style operation on PHP stream. php_stream_truncate_set_size() is a convenience wrapper for php_stream_set_option(stream, PHP_STREAM_OPTION_TRUNCATE_API, PHP_STREAM_TRUNCATE_SET_SIZE, &newsize);, which instructs the underlying stream implementation to change the size of its associated file resource.

The full list of options is a topic unto itself and is beyond the scope of this book. Refer to the source code of stream implementations such as main/streams/plain_wrapper.c and main/streams/xp_socket.c to see the implementation side of these controls.

int php_stream_can_cast(php_stream *stream, int castas); int php_stream_cast(php_stream *stream, int castas, void **ret, int show_err);

Exposes a stream as a more fundamental system type such as a file descriptor or filestream object. castas must be passed as exactly one of the type flags: PHP_STREAM_AS_STDIO, PHP_STREAM_AS_FD, PHP_STREAM_AS_SOCKETD, or PHP_STREAM_AS_FD_FOR_SELECT optionally combined via bitwise OR with PHP_STREAM_CAST_RELEASE, which will invalidate future uses of the owning stream object. To test if a stream can be cast without actually performing the operation, call php_stream_can_cast() instead. Both methods return SUCCESS or FAILURE.

int php_stream_make_seekable(php_stream *origstream, php_stream **newstream, int flags);

If origstream is already seekable, and flags does not contain PHP_STREAM_FORCE_CONVERSION, newstream will simply be set to origstream and this method will return PHP_STREAM_UNCHANGED. Otherwise, a new temporary stream will be created and the remaining contents of origstream will be copied to newstream. Note that any content already read from origstream will not become available as a result of calling this method. If the method succeeds, origstream will be closed and the call will return PHP_STREAM_RELEASED. Should it fail, it will return PHP_STREAM_FAILURE to indicate the temporary stream could not be created, or PHP_STREAM_CRITICAL to indicate that the contents of origstream could not be copied to newstream. Note that a copy failure might result in some or all data from origstream being lost. In addition to PHP_STREAM_FORCE_CONVERSION, flags can also be combined with PHP_STREAM_PREFER_STDIO, which will create a STDIO tempfile rather than a temporary file descriptor.

Directory Access

int php_stream_mkdir(char *path, int mode, int options, php_stream_context *context); int php_stream_rmdir(char *path, int options, php_stream_context *context);

Creates a new directory or remove one. The criteria and method for creating or removing a directory is wrapper-specific; however, all wrappers implementing the mkdir() method are expected to respect the PHP_STREAM_MKDIR_RECURSIVE option. Note that there are no options flags actually defined for php_stream_rmdir(). This argument exists purely for forward compatibility.

php_stream *php_stream_opendir(char *path, int options, php_stream_context *context); php_stream_dirent *php_stream_readdir(php_stream *stream, php_stream_dirent *ent); int php_stream_rewinddir(php_stream *stream); int php_stream_close(php_stream *stream);

Opens, iteratively reads entries from, and closes a directory resource. Directory entries are read in block increments of equal size. The contents of a directory entry can be accessed via ent->d_name.

int php_stream_scandir(char *path, char **namelist[], php_stream_context *context, int (*compare) (const char **a, const char **b)); int php_stream_dirent_alphasort(const char **a, const char **b); int php_stream_dirent_alphasortr(const char **a, const char **b);

php_stream_scandir() will read all entries within a given directory into a vector of char* strings. If a compare functionsuch as one of the alphasort methods shownis provided, the entries will be sorted after being read. Space for the namelist vector and each individual entry will be automatically allocated by the php_stream_scandir() method using nonpersistent storage and must be manually freed after use. For example, a namelist containing 10 entries will have 11 distinct allocationsone for the vector itself, and another for the individual strings within that vector.

Internal/Userspace Conversion

int php_file_le_stream(void); int php_file_le_pstream(void); int php_file_le_stream_filter(void); int php_le_stream_context(void);

Returns list entry type IDs for standard streams, persistent streams, filters, and contexts. These values correspond to the values assigned by zend_register_list_destructors() and are used by helper macros such as php_stream_from_zval().

void php_stream_to_zval(php_stream *stream, zval *zstream); void php_stream_from_zval(php_stream *stream, zval *zstream); void php_stream_from_zval_no_verify(php_stream *stream, zval *zstream);

These helper macros encode an allocated stream to a userspace zval, or decode it back again. Note that these are macros and not regular functions, therefore the stream variable passed to the php_stream_from_zval*(); functions is modified in place. The php_stream_from_zval() macro, unique among the rest, will produce php_error() warnings if the zstream value passed is not a valid PHP Stream resource. Refer back to Chapter 9, "The Resource Data Type," for more information on registering and retrieving resource values.

Contexts

php_stream_context *php_stream_context_alloc(void); void php_stream_context_free(php_stream_context *context);

Allocates or frees a stream context. Refer to Chapter 16, "Diverting the Stream," for a more complete explanation of the usage of stream contexts.

int php_stream_context_set_option(php_stream_context *context, const char *wrappername, const char *optionname, zval *optionvalue); int php_stream_context_get_option(php_stream_context *context, const char *wrappername, const char *optionname, zval ***optionvalue);

Sets or retrieves a context option. Context options are stored in a two-dimensional array of zval* values. The name of the base wrapper defines the first dimension, whereas a wrapper-specific option name defines the second. Wrappers that serve double duty, such as http and https, typically use only one wrapper name (in this case, http) for storing their context options.

php_stream_context *php_stream_context_set(php_stream *stream, php_stream_context *context);

Associates a context with an already active stream instance. Because most context options take effect when the stream is opened, this action will typically have much less impact than specifying the context to the stream creation method.

Notifiers

php_stream_notifier *php_stream_notification_alloc(void); void php_stream_notification_free(php_stream_notifier *notifier); void php_stream_notification_notify(php_stream_context *context, int notifycode, int severity, char *xmsg, int xcode, size_t bytes_sofar, size_t bytes_max, void * ptr TSRMLS_DC);

Refer to Chapter 16 for details on the use of these methods.

Filters

php_stream_filter *php_stream_filter_create(const char *filtername, zval *filterparams, int persistent TSRMLS_DC);

Instantiates a filter using the filter-specific parameters provided. When instantiating a filter object to be placed on a persistent stream, the persistent flag must be set. This can usually be accomplished by using the php_stream_is_persistent() method.

php_stream_filter *php_stream_filter_alloc(php_stream_filter_ops *fops, void *abstract, int persistent); void php_stream_filter_free(php_stream_filter *filter TSRMLS_DC);

Allocates or frees a filter structure. php_stream_filter_alloc() is typically used by filter implementations during instantiation. The free method will automatically call the filter's dtor method to clean up any internal resources.

void php_stream_filter_prepend(php_stream_filter_chain *chain, php_stream_filter *filter); void php_stream_filter_append(php_stream_filter_chain *chain, php_stream_filter *filter); int php_stream_filter_flush(php_stream_filter *filter, int finish); php_stream_filter *php_stream_filter_remove(php_stream_filter *filter, int call_free TSRMLS_DC);

Adds a filter to the beginning or end of a stream's filter stack, flushes its internal buffers, or removes a filter from an active stream. Typically a filter will be flushed prior to removing it so that internally buffered data can be passed to later filters or the read-buffer/write-op as appropriate.

int php_stream_filter_register_factory(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC); int php_stream_filter_unregister_factory( const char *filterpattern TSRMLS_DC); int php_stream_filter_register_factory_volatile(const char *filterpattern, php_stream_filter_factory *factory TSRMLS_DC); int php_stream_filter_unregister_factory_volatile( const char *filterpattern TSRMLS_DC);

Registers or unregisters a stream filter. The volatile variant of these methods allows wrappers to be overridden for the life of a single request only, whereas the nonvolatile versions handle permanent registrations and unregistrations. As with wrappers, volatile filters should be registered and unregistered during request phasesACTIVATE, RUNTIME, DEACTIVATEonly, permanent filters, likewise, should only be registered and unregistered during the STARTUP and SHUTDOWN phases.

Buckets

php_stream_bucket *php_stream_bucket_new(php_stream *stream, char *buf, size_t buflen, int own_buf, int buf_persistent TSRMLS_DC);

Instantiates a bucket object to place on a filter brigade. Refer to Chapter 16 for information on using buckets with custom filter implementations.

void php_stream_bucket_delref(php_stream_bucket *bucket TSRMLS_DC);

Reduce the internal refcount of the named bucket. In practice, buckets rarely exceed a refcount of one, so this call usually destroys the bucket completely.

int php_stream_bucket_split(php_stream_bucket *in, php_stream_bucket **left, php_stream_bucket **right, size_t length TSRMLS_DC);

Divides the contents of a bucket into two new buckets. The in bucket is consumed and delref'd in the process of splitting with length bytes of buffer data placed in the new bucket populated into left, and any remaining data placed in the new bucket populated into right.

void php_stream_bucket_prepend(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC); void php_stream_bucket_append(php_stream_bucket_brigade *brigade, php_stream_bucket *bucket TSRMLS_DC); void php_stream_bucket_unlink(php_stream_bucket *bucket TSRMLS_DC);

Adds or removes a bucket to/from a bucket brigade.

php_stream_bucket *php_stream_bucket_make_writeable(php_stream_bucket *bucket TSRMLS_DC);

Ensures that the data contained in a bucket can be safely modified by the calling scope. If necessary, the bucket will duplicate the contents of its internal buffer in order to make it writeable.

Plainfiles and Standard I/O

php_stream *php_stream_fopen(const char *filename, const char *mode, char **opened_path); php_stream *php_stream_fopen_with_path(char *filename, char *mode, char *include_path, char **opened_path);

Local filesystem variant of the php_stream_open_wrapper() method. This version will not dispatch to any stream wrappers other than the plainfiles wrapper, and does not provide a means to specify a context parameter. Neither versions of this method use the php.ini include_path value; however, the _with_path() variant does allow an include_path set to be specified.

php_stream *php_stream_fopen_from_file(FILE *file, const char *mode); php_stream *php_stream_fopen_from_fd(int fd, const char *mode, const char *persistent_id); php_stream *php_stream_sock_open_from_socket(php_socket_t socket, const char *persistent_id); php_stream *php_stream_fopen_from_pipe(FILE *file, const char *mode);

Casts an already opened file descriptor or stdio file pointer to a PHP stream.

php_stream *php_stream_temp_create(int mode, size_t max_memory_usage); php_stream *php_stream_temp_open(int mode, size_t max_memory_usage, char *buf, size_t length);

Creates a temporary stream suitable for reading and writing. When the stream is closed, any contents within the stream as well as secondary resources are discarded. Initially, temporary data is stored in RAM; however, if the size of the stored data grows beyond max_memory_usage, the contents of the memory stream will be written to a temporary file on disk and all further interim storage will take place there.

char *expand_filepath(const char *filepath, char *real_path TSRMLS_DC);

Resolves symlinks and parent references in the provided filepath to its real target. This method provides a thread-safe replacement to the standard realpath() method.

Transports

php_stream *php_stream_xport_create(const char *name, long namelen, int options, int flags, const char *persistent_id, struct timeval *timeout, php_stream_context *context, char **error_string, int *error_code);

Instantiates a socket transport stream. Depending on the passed flags, this can be a client or server socket, which may or may not immediately connect or start listening.

The flags parameter can consist of either STREAM_XPORT_CLIENT or STREAM_XPORT_SERVER. A client transport can optionally specify either STREAM_XPORT_CONNECT or STREAM_XPORT_CONNECT_ASYNC. Server transports can specify STREAM_XPORT_BIND and STREAM_XPORT_LISTEN.

int php_stream_xport_connect(php_stream *stream, const char *name, long namelen, int asynchronous, struct timeval *timeout, char **error_text, int *error_code TSRMLS_DC);

Connects a transport stream to the specified resource.

int php_stream_xport_bind(php_stream *stream, const char *name, long namelen, char **error_text TSRMLS_DC);

Binds the established stream to a local resource. This can be used for binding server sockets or for source-binding clients prior to connection.

int php_stream_xport_listen(php_stream *stream, int backlog, char **error_text TSRMLS_DC);

Begins listening on the previously bound transport socket.

int php_stream_xport_accept(php_stream *stream, php_stream **client, char **textaddr, int *textaddrlen, void **addr, socklen_t *addrlen, struct timeval *time out, char **error_text TSRMLS_DC);

Accepts a queued connection on a transport socket previously instructed to listen. If no connections are currently queued, this method will block for the period specified by time_out.

int php_stream_xport_get_name(php_stream *stream, int want_peer, char **textaddr, int *textaddrlen, void **addr, socklen_t *addrlen TSRMLS_DC);

Probes the local or remote transport end-point (socket) name.

int php_stream_xport_sendto(php_stream *stream, const char *buf, size_t buflen, long flags, void *addr, socklen_t addrlen TSRMLS_DC); int php_stream_xport_recvfrom(php_stream *stream, char *buf, size_t buflen, long flags, void **addr, socklen_t *addrlen, char **textaddr, int *textaddrlen TSRMLS_DC);

Connectionless send and receive methods.

int php_stream_xport_crypto_setup(php_stream *stream, php_stream_xport_crypt_method_t crypto_method, php_stream *session_stream TSRMLS_DC); int php_stream_xport_crypto_enable(php_stream *stream, int activate TSRMLS_DC);

Sets up and activates/deactivates encryption on the specified transport stream. In practice only the SSL/TLS crypto methods are implemented and these are only typically used with the TCP transport.

int php_stream_xport_register(char *protocol, php_stream_transport_factory factory TSRMLS_DC); typedef php_stream *(*php_stream_transport_factory)( const char *proto, long protolen, char *resourcename, long resourcenamelen, const char *persistent_id, int options, int flags, struct timeval *timeout, php_stream_context *context STREAMS_DC TSRMLS_DC); int php_stream_xport_unregister(char *protocol TSRMLS_DC);

Registers or unregisters a stream transport factory. Transport factory methods follow the same pattern as stream protocol wrapper opener functions. Refer to Chapter 15 for an overview of stream creation methods.

HashTable *php_stream_xport_get_hash(void);

Returns a pointer to the internal transport registry hash.

int php_network_parse_network_address_with_port(const char *addr, long addrlen, struct sockaddr *sa, socklen_t *sl TSRMLS_DC);

Parses an inet family transport URI into its component parts. If the host portion of the URI is hostname it will be automatically resolved to its IP address. The appropriate address family, address, and port data are loaded into the sa sockaddr structure and its final size is populated into sl.

Miscellaneous

int php_register_url_stream_wrapper(char *protocol, php_stream_wrapper *wrapper TSRMLS_DC); int php_unregister_url_stream_wrapper(char *protocol TSRMLS_DC); int php_register_url_stream_wrapper_volatile(char *protocol, php_stream_wrapper *wrapper TSRMLS_DC); int php_unregister_url_stream_wrapper_volatile(char *protocol TSRMLS_DC);

Registers or unregisters a stream protocol wrapper. The volatile variant of these methods allows wrappers to be overridden for the life of a single request only, whereas the nonvolatile versions handle permanent registrations and unregistrations. Needless to say, volatile wrappers should be registered and unregistered during request phasesACTIVATE, RUNTIME, DEACTIVATEonly, permanent wrappers, by contrast, should only be registered and unregistered during the STARTUP and SHUTDOWN phases. Refer to Chapter 15 for more information.

void php_stream_wrapper_log_error(php_stream_wrapper *wrapper, int options TSRMLS_DC, const char *format, ...);

Reports a stream error via the wrapper subsystem. This method is typically called from wrapper operations such as stream_open. Refer to Chapter 15 for more information on reporting wrapper errors.

HashTable *php_stream_get_url_stream_wrappers_hash(void); HashTable *php_stream_get_url_stream_wrappers_hash_global(void); HashTable *php_get_stream_filters_hash(void); HashTable *php_get_stream_filters_hash_global(void);

Returns a reference to the internal registry of wrappers and filters. The _global() variants of these methods contain the persistent wrapper and filter definitions while the non _global() versions return this list as it has been modified by volatile registrations.

int php_stream_is(php_stream *stream, php_stream_ops *ops);

Returns nonzero if stream implements the named stream ops.

int php_stream_is_persistent(php_stream *stream);

Returns a nonzero value if the named stream instance is meant to be persistent between requests.

int php_is_url(char *path);

Returns a nonzero value if the named path specifies a network-based resource.

char *php_strip_url_passwd(char *path);

Strips the password from a standard formatted URL. Note that this method modifies the provided path in place; therefore, the value provided must be owned by the calling process and be modifiable.