Annotation of embedaddon/php/README.STREAMS, revision 1.1
1.1 ! misho 1: An Overview of the PHP Streams abstraction
! 2: ==========================================
! 3: $Id: README.STREAMS 242949 2007-09-26 15:44:16Z cvs2svn $
! 4:
! 5: WARNING: some prototypes in this file are out of date.
! 6: The information contained here is being integrated into
! 7: the PHP manual - stay tuned...
! 8:
! 9: Please send comments to: Wez Furlong <wez@thebrainroom.com>
! 10:
! 11: Why Streams?
! 12: ============
! 13: You may have noticed a shed-load of issock parameters flying around the PHP
! 14: code; we don't want them - they are ugly and cumbersome and force you to
! 15: special case sockets and files every time you need to work with a "user-level"
! 16: PHP file pointer.
! 17: Streams take care of that and present the PHP extension coder with an ANSI
! 18: stdio-alike API that looks much nicer and can be extended to support non file
! 19: based data sources.
! 20:
! 21: Using Streams
! 22: =============
! 23: Streams use a php_stream* parameter just as ANSI stdio (fread etc.) use a
! 24: FILE* parameter.
! 25:
! 26: The main functions are:
! 27:
! 28: PHPAPI size_t php_stream_read(php_stream * stream, char * buf, size_t count);
! 29: PHPAPI size_t php_stream_write(php_stream * stream, const char * buf, size_t
! 30: count);
! 31: PHPAPI size_t php_stream_printf(php_stream * stream TSRMLS_DC,
! 32: const char * fmt, ...);
! 33: PHPAPI int php_stream_eof(php_stream * stream);
! 34: PHPAPI int php_stream_getc(php_stream * stream);
! 35: PHPAPI char *php_stream_gets(php_stream * stream, char *buf, size_t maxlen);
! 36: PHPAPI int php_stream_close(php_stream * stream);
! 37: PHPAPI int php_stream_flush(php_stream * stream);
! 38: PHPAPI int php_stream_seek(php_stream * stream, off_t offset, int whence);
! 39: PHPAPI off_t php_stream_tell(php_stream * stream);
! 40: PHPAPI int php_stream_lock(php_stream * stream, int mode);
! 41:
! 42: These (should) behave in the same way as the ANSI stdio functions with similar
! 43: names: fread, fwrite, fprintf, feof, fgetc, fgets, fclose, fflush, fseek, ftell, flock.
! 44:
! 45: Opening Streams
! 46: ===============
! 47: In most cases, you should use this API:
! 48:
! 49: PHPAPI php_stream *php_stream_open_wrapper(char *path, char *mode,
! 50: int options, char **opened_path TSRMLS_DC);
! 51:
! 52: Where:
! 53: path is the file or resource to open.
! 54: mode is the stdio compatible mode eg: "wb", "rb" etc.
! 55: options is a combination of the following values:
! 56: IGNORE_PATH (default) - don't use include path to search for the file
! 57: USE_PATH - use include path to search for the file
! 58: IGNORE_URL - do not use plugin wrappers
! 59: REPORT_ERRORS - show errors in a standard format if something
! 60: goes wrong.
! 61: STREAM_MUST_SEEK - If you really need to be able to seek the stream
! 62: and don't need to be able to write to the original
! 63: file/URL, use this option to arrange for the stream
! 64: to be copied (if needed) into a stream that can
! 65: be seek()ed.
! 66:
! 67: opened_path is used to return the path of the actual file opened,
! 68: but if you used STREAM_MUST_SEEK, may not be valid. You are
! 69: responsible for efree()ing opened_path. opened_path may be (and usually
! 70: is) NULL.
! 71:
! 72: If you need to open a specific stream, or convert standard resources into
! 73: streams there are a range of functions to do this defined in php_streams.h.
! 74: A brief list of the most commonly used functions:
! 75:
! 76: PHPAPI php_stream *php_stream_fopen_from_file(FILE *file, const char *mode);
! 77: Convert a FILE * into a stream.
! 78:
! 79: PHPAPI php_stream *php_stream_fopen_tmpfile(void);
! 80: Open a FILE * with tmpfile() and convert into a stream.
! 81:
! 82: PHPAPI php_stream *php_stream_fopen_temporary_file(const char *dir,
! 83: const char *pfx, char **opened_path TSRMLS_DC);
! 84: Generate a temporary file name and open it.
! 85:
! 86: There are some network enabled relatives in php_network.h:
! 87:
! 88: PHPAPI php_stream *php_stream_sock_open_from_socket(int socket, int persistent);
! 89: Convert a socket into a stream.
! 90:
! 91: PHPAPI php_stream *php_stream_sock_open_host(const char *host, unsigned short port,
! 92: int socktype, int timeout, int persistent);
! 93: Open a connection to a host and return a stream.
! 94:
! 95: PHPAPI php_stream *php_stream_sock_open_unix(const char *path, int persistent,
! 96: struct timeval *timeout);
! 97: Open a UNIX domain socket.
! 98:
! 99:
! 100: Stream Utilities
! 101: ================
! 102:
! 103: If you need to copy some data from one stream to another, you will be please
! 104: to know that the streams API provides a standard way to do this:
! 105:
! 106: PHPAPI size_t php_stream_copy_to_stream(php_stream *src,
! 107: php_stream *dest, size_t maxlen);
! 108:
! 109: If you want to copy all remaining data from the src stream, pass
! 110: PHP_STREAM_COPY_ALL as the maxlen parameter, otherwise maxlen indicates the
! 111: number of bytes to copy.
! 112: This function will try to use mmap where available to make the copying more
! 113: efficient.
! 114:
! 115: If you want to read the contents of a stream into an allocated memory buffer,
! 116: you should use:
! 117:
! 118: PHPAPI size_t php_stream_copy_to_mem(php_stream *src, char **buf,
! 119: size_t maxlen, int persistent);
! 120:
! 121: This function will set buf to the address of the buffer that it allocated,
! 122: which will be maxlen bytes in length, or will be the entire length of the
! 123: data remaining on the stream if you set maxlen to PHP_STREAM_COPY_ALL.
! 124: The buffer is allocated using pemalloc(); you need to call pefree() to
! 125: release the memory when you are done.
! 126: As with copy_to_stream, this function will try use mmap where it can.
! 127:
! 128: If you have an existing stream and need to be able to seek() it, you
! 129: can use this function to copy the contents into a new stream that can
! 130: be seek()ed:
! 131:
! 132: PHPAPI int php_stream_make_seekable(php_stream *origstream, php_stream **newstream);
! 133:
! 134: It returns one of the following values:
! 135: #define PHP_STREAM_UNCHANGED 0 /* orig stream was seekable anyway */
! 136: #define PHP_STREAM_RELEASED 1 /* newstream should be used; origstream is no longer valid */
! 137: #define PHP_STREAM_FAILED 2 /* an error occurred while attempting conversion */
! 138: #define PHP_STREAM_CRITICAL 3 /* an error occurred; origstream is in an unknown state; you should close origstream */
! 139:
! 140: make_seekable will always set newstream to be the stream that is valid
! 141: if the function succeeds.
! 142: When you have finished, remember to close the stream.
! 143:
! 144: NOTE: If you only need to seek forward, there is no need to call this
! 145: function, as the php_stream_seek can emulate forward seeking when the
! 146: whence parameter is SEEK_CUR.
! 147:
! 148: NOTE: Writing to the stream may not affect the original source, so it
! 149: only makes sense to use this for read-only use.
! 150:
! 151: NOTE: If the origstream is network based, this function will block
! 152: until the whole contents have been downloaded.
! 153:
! 154: NOTE: Never call this function with an origstream that is referenced
! 155: as a resource! It will close the origstream on success, and this
! 156: can lead to a crash when the resource is later used/released.
! 157:
! 158: NOTE: If you are opening a stream and need it to be seekable, use the
! 159: STREAM_MUST_SEEK option to php_stream_open_wrapper();
! 160:
! 161: PHPAPI int php_stream_supports_lock(php_stream * stream);
! 162:
! 163: This function will return either 1 (success) or 0 (failure) indicating whether or
! 164: not a lock can be set on this stream. Typically you can only set locks on stdio streams.
! 165:
! 166: Casting Streams
! 167: ===============
! 168: What if your extension needs to access the FILE* of a user level file pointer?
! 169: You need to "cast" the stream into a FILE*, and this is how you do it:
! 170:
! 171: FILE * fp;
! 172: php_stream * stream; /* already opened */
! 173:
! 174: if (php_stream_cast(stream, PHP_STREAM_AS_STDIO, (void*)&fp, REPORT_ERRORS) == FAILURE) {
! 175: RETURN_FALSE;
! 176: }
! 177:
! 178: The prototype is:
! 179:
! 180: PHPAPI int php_stream_cast(php_stream * stream, int castas, void ** ret, int
! 181: show_err);
! 182:
! 183: The show_err parameter, if non-zero, will cause the function to display an
! 184: appropriate error message of type E_WARNING if the cast fails.
! 185:
! 186: castas can be one of the following values:
! 187: PHP_STREAM_AS_STDIO - a stdio FILE*
! 188: PHP_STREAM_AS_FD - a generic file descriptor
! 189: PHP_STREAM_AS_SOCKETD - a socket descriptor
! 190:
! 191: If you ask a socket stream for a FILE*, the abstraction will use fdopen to
! 192: create it for you. Be warned that doing so may cause buffered data to be lost
! 193: if you mix ANSI stdio calls on the FILE* with php stream calls on the stream.
! 194:
! 195: If your system has the fopencookie function, php streams can synthesize a
! 196: FILE* on top of any stream, which is useful for SSL sockets, memory based
! 197: streams, data base streams etc. etc.
! 198:
! 199: In situations where this is not desirable, you should query the stream
! 200: to see if it naturally supports FILE *. You can use this code snippet
! 201: for this purpose:
! 202:
! 203: if (php_stream_is(stream, PHP_STREAM_IS_STDIO)) {
! 204: /* can safely cast to FILE* with no adverse side effects */
! 205: }
! 206:
! 207: You can use:
! 208:
! 209: PHPAPI int php_stream_can_cast(php_stream * stream, int castas)
! 210:
! 211: to find out if a stream can be cast, without actually performing the cast, so
! 212: to check if a stream is a socket you might use:
! 213:
! 214: if (php_stream_can_cast(stream, PHP_STREAM_AS_SOCKETD) == SUCCESS) {
! 215: /* it can be a socket */
! 216: }
! 217:
! 218: Please note the difference between php_stream_is and php_stream_can_cast;
! 219: stream_is tells you if the stream is a particular type of stream, whereas
! 220: can_cast tells you if the stream can be forced into the form you request.
! 221: The former doesn't change anything, while the later *might* change some
! 222: state in the stream.
! 223:
! 224: Stream Internals
! 225: ================
! 226:
! 227: There are two main structures associated with a stream - the php_stream
! 228: itself, which holds some state information (and possibly a buffer) and a
! 229: php_stream_ops structure, which holds the "virtual method table" for the
! 230: underlying implementation.
! 231:
! 232: The php_streams ops struct consists of pointers to methods that implement
! 233: read, write, close, flush, seek, gets and cast operations. Of these, an
! 234: implementation need only implement write, read, close and flush. The gets
! 235: method is intended to be used for streams if there is an underlying method
! 236: that can efficiently behave as fgets. The ops struct also contains a label
! 237: for the implementation that will be used when printing error messages - the
! 238: stdio implementation has a label of "STDIO" for example.
! 239:
! 240: The idea is that a stream implementation defines a php_stream_ops struct, and
! 241: associates it with a php_stream using php_stream_alloc.
! 242:
! 243: As an example, the php_stream_fopen() function looks like this:
! 244:
! 245: PHPAPI php_stream * php_stream_fopen(const char * filename, const char * mode)
! 246: {
! 247: FILE * fp = fopen(filename, mode);
! 248: php_stream * ret;
! 249:
! 250: if (fp) {
! 251: ret = php_stream_alloc(&php_stream_stdio_ops, fp, 0, 0, mode);
! 252: if (ret)
! 253: return ret;
! 254:
! 255: fclose(fp);
! 256: }
! 257: return NULL;
! 258: }
! 259:
! 260: php_stream_stdio_ops is a php_stream_ops structure that can be used to handle
! 261: FILE* based streams.
! 262:
! 263: A socket based stream would use code similar to that above to create a stream
! 264: to be passed back to fopen_wrapper (or it's yet to be implemented successor).
! 265:
! 266: The prototype for php_stream_alloc is this:
! 267:
! 268: PHPAPI php_stream * php_stream_alloc(php_stream_ops * ops, void * abstract,
! 269: size_t bufsize, int persistent, const char * mode)
! 270:
! 271: ops is a pointer to the implementation,
! 272: abstract holds implementation specific data that is relevant to this instance
! 273: of the stream,
! 274: bufsize is the size of the buffer to use - if 0, then buffering at the stream
! 275: level will be disabled (recommended for underlying sources that implement
! 276: their own buffering - such a FILE*),
! 277: persistent controls how the memory is to be allocated - persistently so that
! 278: it lasts across requests, or non-persistently so that it is freed at the end
! 279: of a request (it uses pemalloc),
! 280: mode is the stdio-like mode of operation - php streams places no real meaning
! 281: in the mode parameter, except that it checks for a 'w' in the string when
! 282: attempting to write (this may change).
! 283:
! 284: The mode parameter is passed on to fdopen/fopencookie when the stream is cast
! 285: into a FILE*, so it should be compatible with the mode parameter of fopen().
! 286:
! 287: Writing your own stream implementation
! 288: ======================================
! 289:
! 290: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! 291: RULE #1: when writing your own streams: make sure you have configured PHP with
! 292: --enable-debug.
! 293: I've taken some great pains to hook into the Zend memory manager to help track
! 294: down allocation problems. It will also help you spot incorrect use of the
! 295: STREAMS_DC, STREAMS_CC and the semi-private STREAMS_REL_CC macros for function
! 296: definitions.
! 297: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! 298:
! 299: RULE #2: Please use the stdio stream as a reference; it will help you
! 300: understand the semantics of the stream operations, and it will always
! 301: be more up to date than these docs :-)
! 302:
! 303: First, you need to figure out what data you need to associate with the
! 304: php_stream. For example, you might need a pointer to some memory for memory
! 305: based streams, or if you were making a stream to read data from an RDBMS like
! 306: MySQL, you might want to store the connection and rowset handles.
! 307:
! 308: The stream has a field called abstract that you can use to hold this data.
! 309: If you need to store more than a single field of data, define a structure to
! 310: hold it, allocate it (use pemalloc with the persistent flag set
! 311: appropriately), and use the abstract pointer to refer to it.
! 312:
! 313: For structured state you might have this:
! 314:
! 315: struct my_state {
! 316: MYSQL conn;
! 317: MYSQL_RES * result;
! 318: };
! 319:
! 320: struct my_state * state = pemalloc(sizeof(struct my_state), persistent);
! 321:
! 322: /* initialize the connection, and run a query, using the fields in state to
! 323: * hold the results */
! 324:
! 325: state->result = mysql_use_result(&state->conn);
! 326:
! 327: /* now allocate the stream itself */
! 328: stream = php_stream_alloc(&my_ops, state, 0, persistent, "r");
! 329:
! 330: /* now stream->abstract == state */
! 331:
! 332: Once you have that part figured out, you can write your implementation and
! 333: define the your own php_stream_ops struct (we called it my_ops in the above
! 334: example).
! 335:
! 336: For example, for reading from this weird MySQL stream:
! 337:
! 338: static size_t php_mysqlop_read(php_stream * stream, char * buf, size_t count)
! 339: {
! 340: struct my_state * state = (struct my_state*)stream->abstract;
! 341:
! 342: if (buf == NULL && count == 0) {
! 343: /* in this special case, php_streams is asking if we have reached the
! 344: * end of file */
! 345: if (... at end of file ...)
! 346: return EOF;
! 347: else
! 348: return 0;
! 349: }
! 350:
! 351: /* pull out some data from the stream and put it in buf */
! 352: ... mysql_fetch_row(state->result) ...
! 353: /* we could do something strange, like format the data as XML here,
! 354: and place that in the buf, but that brings in some complexities,
! 355: such as coping with a buffer size too small to hold the data,
! 356: so I won't even go in to how to do that here */
! 357: }
! 358:
! 359: Implement the other operations - remember that write, read, close and flush
! 360: are all mandatory. The rest are optional. Declare your stream ops struct:
! 361:
! 362: php_stream_ops my_ops = {
! 363: php_mysqlop_write, php_mysqlop_read, php_mysqlop_close,
! 364: php_mysqlop_flush, NULL, NULL, NULL,
! 365: "Strange MySQL example"
! 366: }
! 367:
! 368: Thats it!
! 369:
! 370: Take a look at the STDIO implementation in streams.c for more information
! 371: about how these operations work.
! 372: The main thing to remember is that in your close operation you need to release
! 373: and free the resources you allocated for the abstract field. In the case of
! 374: the example above, you need to use mysql_free_result on the rowset, close the
! 375: connection and then use pefree to dispose of the struct you allocated.
! 376: You may read the stream->persistent field to determine if your struct was
! 377: allocated in persistent mode or not.
! 378:
! 379: vim:tw=78:et
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.STREAMS CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php