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.

Argument	Purpose
ops	Structure containing a list of callback operations for performing read, write, flush, close, and other operations.
abstract	Attaches an arbitrary data structure to the stream instance, typically referring to the underlying data resource.
persistent_id	Unique identifier for this stream resource used for retrieving persistent stream instances.
mode	fopen mode to associate with this stream instance (such as r, w, a, r+, and so on).

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.

close_options Flags	Description
PHP_STREAM_FREE_CALL_DTOR	Call the stream's ops->close() method
PHP_STREAM_FREE_RELEASE_STREAM	Free memory allocated to store the stream instance
PHP_STREAM_FREE_PRESERVE_HANDLE	Passed to ops->close() to instruct it not to close the underlying handle
PHP_STREAM_FREE_RSRC_DTOR	Used internally by the streams layer to avoid recursion when destroying the stream's associated resource
PHP_STREAM_FREE_PERSISTENT	Explicitly close an otherwise persistent stream instance
PHP_STREAM_FREE_CLOSE	Combination of PHP_STREAM_FREE_CALL_DTOR and PHP_STREAM_FREE_RELEASE_STREAM
PHP_STREAM_FREE_CLOSE_CASTED	Combination of PHP_STREAM_FREE_CLOSE and PHP_STREAM_FREE_PRESERVE_HANDLE
PHP_STREAM_FREE_CLOSE_PERSISTENT	Combination of PHP_STREAM_FREE_CLOSE and PHP_STREAM_FREE_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.

Argument	Purpose
path	Full URI of resource to be mapped to its wrapper structure.
path_for_open	Populated with (possibly) modified version of path to use in actual open call.
options	Bitmask flag containing zero or more of the following options: IGNORE_URL, STREAM_LOCATE_WRAPPERS_ONLY, and REPORT_ERRORS. Refer to Chapter 14 for explanations of these flags.

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.

Argument	Purpose
path	URI pointing to location of resource to be opened.
mode	Access mode to apply to file being opened (such as r, w+, a, and so on).
options	Zero or more of the stream open options described in Chapter 14.
opened_path	Populated with the actual location of the opened resource. Due to symlinks and redirects, this will commonly be different from the actual path requested.
context	Stream context to be used while opening or accessing the stream.

 

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.

Argument	Purpose
stream	Stream instance to read from.
buf	Buffer to store results to. For methods that return char*, if buf is passed as NULL, a buffer of appropriate size will be emalloc'd to the appropriate size.
maxlen	Maximum number of bytes to read from the stream.
delim	"End of line" delimiter. Sequence at which to stop reading from the stream. Does not require a terminating NULL byte.
delim_len	Length of delimiter string, not including any optional terminating NULL characters.
returned_len	Length of string returned by methods otherwise returning a char* buffer.

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.

Argument	Purpose
stream	Stream to write data to
buf	Buffer containing data to be written to stream
count	Number of bytes of data contained in buf
c	Single character to write to stream
fmt	sprintf() style format specifier
...	Variable argument list corresponding to fmt specifier

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.

Argument	Purpose
stream	Stream to map
offset	Beginning offset in the stream's contents from which to map
length	Number of bytes to map; use PHP_STREAM_COPY_ALL to map all of the remaining data (however much is available)
mode	Set to PHP_STREAM_MMAP_MAP_RANGE; other values are used internally by the streams layer
mapped_len	Populated with the actual number of bytes mapped to the pointer returned by this method

 

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);.

Argument	Purpose
stream	Stream to seek or report the location on
offset	Position to seek to relative to the whence
whence	One of SEEK_SET (relative to beginning of stream), SEEK_CUR (relative to current position), or SEEK_END (relative to end of file)

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.

Argument	Purpose
stream	Active stream instance to retrieve fstat() information from.
path	URL to a local or remote file resource to retrieve stat() data from.
flags	If set to PHP_STREAM_URL_STAT_LINK, only the immediate resource pointed to by path will be inspected. If this flag is not set, symlinks will be followed to a real resource.
ssb	Stat buffer to populate filestat information into.
context	Stream context to apply when attempting to locate the local or remote resource.

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.

Argument	Purpose
stream	Stream to be cast.
castas	Type of resource to cast the stream to.
ret	Pointer to a local variable to store the casted stream to.
show_err	Set to a nonzero value to raise php_errors()s if the cast encounters errors.

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.

Argument	Purpose
path	URI describing directory to be created or removed.
mode	POSIX access mode to apply to the newly created directory.
options	Bitmask flag argument withcurrentlyone option: PHP_STREAM_MKDIR_RECURSIVE, which applies only to the mkdir() variant of these methods. When used, any nonexisting parent directories required by the given path will be implicitly created as well.
context	Stream context to apply to wrapper execution.

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.

Argument	Purpose
path	URI pointing to directory to be examined.
options	Optional parameters to pass during stream creation. Refer to Chapter 14 for a listing of these options and what they do.
context	Stream context to apply while opening this directory resource.
stream	Active directory stream instance to read from, rewind, or close.
ent	Directory entry buffer that will be populated with the next directory entry 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.

Argument	Purpose
path	URI pointing to the directory to scan for entries.
namelist	Passed as a pointer to local char** storage. This will be modified by reference by the scandir method.
context	Stream context to use while scanning the directory.
compare	Comparison function to use for sorting. Can be either of the alphasort methods given previously, or any callback that accepts two elements as its input and returns -1, 0, or 1 to indicate less-than, equal, or greater-than, respectively.

 

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.

Argument	Purpose
context	Context container to set or retrieve options on.
wrappername	Name of the base wrapper for which this option applies.
optionname	Wrapper-specific option name to get or set.
optionvalue	Depending on the specific method called, either a zval* value to store into the context option, or pointer to a local zval** variable to fetch a previously stored value back into. Note that when storing a value it is explicitly separated (copied) by the streams layer, detaching it from the calling scope's ownership.

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.

Argument	Purpose
filtername	Name of the filter to instantiate.
filterparams	Optional zval* containing filter-specific parameters. Refer to documentation for the filter being instantiated for the types and values accepted.
persistent	Binary flag indicating whether the filter will be placed on a persistent stream.

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.

Argument	Purpose
fops	Filter ops structure containing callbacks to use with this filter instance.
abstract	Arbitrary data pointer to associate with the filter instance.
persistent	Flag indicating whether the filter will be placed on a persistent stream.

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.

Argument	Purpose
chain	Filter chain to add the named filter to. Typically one of stream->readfilters or stream->writefilters.
filter	Filter instance to add, flush, or remove.
finish	When set to a nonzero value, the filter is instructed to flush as much data from its internal buffers as possible. Otherwise, the filter can choose to only flush the current block of data while retaining some for the next cycle.
call_free	Automatically call php_stream_filter_free() after removing it from its stream's filter chain.

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.

Argument	Purpose
stream	Reference to the stream this bucket will ultimately be associated with.
buf	Data buffer to assign to this bucket.
buflen	Length of buf in bytes.
own_buf	Set to a nonzero value if buf can be safely altered or freed by another filter or the streams layer. If this and buf_persistent are set to 0, and the target stream is not persistent, buf will be automatically copied so that the bucket owns a modifiable buffer.
buf_persistent	Set to a nonzero value if the passed buf data will remain available and unchanged for the life of the current request.

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.

Argument	Purpose
file / fd	Existing file descriptor or stdio file pointer to wrap in a PHP stream
mode	fopen mode to associate with the stream
persistent_id	Persistent ID to assign to the 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.

Argument	Purpose
mode	One of: TEMP_STREAM_DEFAULT, TEMP_STREAM_READONLY, or TEMP_STREAM_TAKE_BUFFER.
max_memory_usage	Maximum amount of memory to allocate for temporary data storage. Once this limit is exceeded, a temp file will be used as the storage medium instead.
buf	Initial buffer to create the temporary stream with.
length	Size of buf in bytes.

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.

Argument	Purpose
name	Transport URI. If no protocol specifier is given, tcp:// is assumed for backward compatibility with the userspace fsockopen() command.
namelen	Length of a name argument, not including its trailing NULL.
options	The same options parameter used with php_stream_open_wrapper().
flags	Bitwise OR combination of the STREAM_XPORT flags.
persistent_id	Persistent ID associated with this transport. If available, and the socket is still live, the existing stream will be reused rather than opening a new one.
timeout	Maximum time to block while performing a synchronous connection.
context	Optional stream context.
error_string	Populated with a descriptive error if one occurs.
error_code	Populated with a numeric error code if one occurs.

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.

Flag	Meaning
STREAM_XPORT_CLIENT	Create a client-style transport.
STREAM_XPORT_SERVER	Create a server-style transport.
STREAM_XPORT_CONNECT	Immediately connect to the specified resource using a blocking (synchronous) call.
STREAM_XPORT_BIND	Bind to the specified local resource.
STREAM_XPORT_LISTEN	Listen for inbound connections on the transport socket. Typically requires the inclusion of STREAM_XPORT_BIND. By default, a backlog of five connections will be queued.
STREAM_XPORT_CONNECT_ASYNC	Begin connecting to the specified resource asynchronously.

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.

Argument	Purpose
stream	Transport stream to connect to the specified resource
name	Transport protocolspecific resource specified to connect to
namelen	Length of resource specifier
asynchronous	Set to a nonzero value to connect asynchronously
timeout	Maximum length of time to wait for a successful connection
error_text	Populated with descriptive error message on failure
error_code	Populated with numeric error code

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.

Argument	Purpose
stream	Transport stream to bind to a local resource
name	String describing the local resource to bind to
namelen	Length of name excluding its trailing NULL byte
error_test	Populated with textual error message if the bind was unsuccessful

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

Begins listening on the previously bound transport socket.

Argument	Meaning
stream	Transport stream to bind to a local resource
backlog	Number of unaccepted connections to queue before rejecting additional connection attempts
error_test	Populated with textual error message if the bind was unsuccessful

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.

Argument	Purpose
stream	Server transport stream previously bound and instructed to listen. Connections will be accepted from this transport's backlog.
client	Populated with newly created transport stream using accepted connection.
textaddr	Populated with textual representation of addr.
textaddrlen	Populated with length of textaddr.
addr	Populated with transport-specific address structure.
addrlen	Populated with length of transport-specific address structure.
time_out	Maximum length of time to wait for an inbound connection. NULL to wait indefinitely.
error_text	Populated with textual error message if one occurs.

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.

Argument	Purpose
stream	Connected transport stream
want_peer	Set to nonzero to retrieve the remote end-point's information
textaddr	Populated with textual representation of address information
textaddrlen	Populated with length of textaddr
addr	Populated with transport protocolspecific address information
addrlen	Populated with length of addr

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.

Argument	Meaning
stream	Transport stream to use for sending or receiving.
buf	Data to be sent or buffer to populate received data into.
buflen	Length of data to send or length of buffer to receive data into.
flags	Can optionally be set to STREAM_OOB to send or receive out-of-band data. When receiving, can also be set to or combined with STREAM_PEEK to inspect data without consuming it.
addr	When sending: protocol-specific address record to send to. When receiving: populated with protocol-specific source address record.
addrlen	Length of addr in bytes.
textaddr	Populated with textual representation of source address.
textaddrlen	Populated with length of textaddr.

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.

Argument	Purpose
stream	Transport stream to setup cryptography on.
crypto_method	One of: STREAM_CRYPTO_METHOD_SSLv2_CLIENT, STREAM_CRYPTO_METHOD_SSLv3_CLIENT, STREAM_CRYPTO_METHOD_SSLv23_CLIENT, STREAM_CRYPTO_METHOD_TLS_CLIENT, STREAM_CRYPTO_METHOD_SSLv2_SERVER, STREAM_CRYPTO_METHOD_SSLv3_SERVER, STREAM_CRYPTO_METHOD_SSLv23_SERVER, or STREAM_CRYPTO_METHOD_TLS_SERVER.
session_stream	If provided, the new crypto setup will inherit session parameters from a previously crypto-enabled transport stream.
activate	When set to a nonzero value, the crypto-layer will be enabled; when set to zero, it will be turned off.

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.

Argument	Purpose
protocol	Name of protocol to register or unregister.
factory	Factory method called when a transport of the specified protocol is instantiated.
proto	Name of transport protocol being instantiated.
protolen	Length of proto.
resourcename	Protocol-specific URI indicating resource to connect to.
resourcenamelen	Length of resourcename.
persistent_id	Persistent ID associated with the transport stream being instantiated.
options	Option values as passed to php_stream_xport_create().
flags	Flag values as passed to php_stream_xport_create().
timeout	Default timeout value for transport.
context	Optional context parameter to be associated with the stream.

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.

Argument	Purpose
wrapper	Reference to the currently active wrapper.
options	Typically passed through from the parameter stack. If the REPORT_ERRORS flag is set, the error message will be dispatched via PHP's normal error handling mechanism with php_error(). If it's not set, the message will be appended to the current wrappers error log.
format	sprintf() style format specifier.
...	Variable argument list corresponding to format.

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.