X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Ffastbuf.h;h=633155fe0b7cf9c98a5d5e9f13780924cdf9f0f9;hb=2bf6703492289fbf3e166b6fa4722f5ad4bd5ea6;hp=33d88cfe36c84839b8aa7ef5f755f5f41492aa94;hpb=ed92f16d9ab9f8bb4ef00d3e6646c05bc3c1ae85;p=libucw.git diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h index 33d88cfe..633155fe 100644 --- a/ucw/fastbuf.h +++ b/ucw/fastbuf.h @@ -35,7 +35,7 @@ * * Here `bptr` points to the next character to be read. After the last character is * read, `bptr == bstop` and the `refill` callback gets called upon the next read - * attempt to bring further data. This gives us an easy way how to implement bungetc(). + * attempt to bring further data. This gives us an easy way how to implement @bungetc(). * * When writing, the situation looks like: * @@ -61,7 +61,7 @@ * the modifications will be undone before calling the next * fastbuf operation * * 2 if the user is allowed to overwrite the data in the buffer - * if bdirect_read_commit_modified() is called afterwards. + * if @bdirect_read_commit_modified() is called afterwards. * In this case, the back-end must be prepared for trimming * of the buffer which is done by the commit function. * @@ -79,7 +79,7 @@ struct fastbuf { ucw_off_t pos; /* Position of bstop in the file */ int (*refill)(struct fastbuf *); /* Get a buffer with new data, returns 0 on EOF */ void (*spout)(struct fastbuf *); /* Write buffer data to the file */ - int (*seek)(struct fastbuf *, ucw_off_t, int);/* Slow path for bseek(), buffer already flushed; returns success */ + int (*seek)(struct fastbuf *, ucw_off_t, int);/* Slow path for @bseek(), buffer already flushed; returns success */ void (*close)(struct fastbuf *); /* Close the stream */ int (*config)(struct fastbuf *, uns, int); /* Configure the stream */ int can_overwrite_buffer; /* Can the buffer be altered? 0=never, 1=temporarily, 2=permanently */ @@ -141,7 +141,7 @@ struct fastbuf *bopen_tmp_file(struct fb_params *params); * Creates a fastbuf from a file descriptor @fd and sets its filename * to @name (the name is used only in error messages). * When the fastbuf is closed, the fd is closed as well. You can override - * this behavior by calling bconfig(). + * this behavior by calling @bconfig(). */ struct fastbuf *bopen_fd_name(int fd, struct fb_params *params, const char *name); static inline struct fastbuf *bopen_fd(int fd, struct fb_params *params) /** Same as above, but with an auto-generated filename. **/ @@ -161,16 +161,16 @@ void bfilesync(struct fastbuf *b); * up any parameters, there is a couple of shortcuts. ***/ -struct fastbuf *bopen(const char *name, uns mode, uns buflen); /** Equivalent to bopen_file() with `FB_STD` back-end. **/ -struct fastbuf *bopen_try(const char *name, uns mode, uns buflen); /** Equivalent to bopen_file_try() with `FB_STD` back-end. **/ -struct fastbuf *bopen_tmp(uns buflen); /** Equivalent to bopen_tmp_file() with `FB_STD` back-end. **/ -struct fastbuf *bfdopen(int fd, uns buflen); /** Equivalent to bopen_fd() with `FB_STD` back-end. **/ -struct fastbuf *bfdopen_shared(int fd, uns buflen); /** Like bfdopen(), but it does not close the @fd on bclose(). **/ +struct fastbuf *bopen(const char *name, uns mode, uns buflen); /** Equivalent to @bopen_file() with `FB_STD` back-end. **/ +struct fastbuf *bopen_try(const char *name, uns mode, uns buflen); /** Equivalent to @bopen_file_try() with `FB_STD` back-end. **/ +struct fastbuf *bopen_tmp(uns buflen); /** Equivalent to @bopen_tmp_file() with `FB_STD` back-end. **/ +struct fastbuf *bfdopen(int fd, uns buflen); /** Equivalent to @bopen_fd() with `FB_STD` back-end. **/ +struct fastbuf *bfdopen_shared(int fd, uns buflen); /** Like @bfdopen(), but it does not close the @fd on @bclose(). **/ /*** * === Temporary files [[fbtemp]] * - * Usually, bopen_tmp_file() is the best way how to come to a temporary file. + * Usually, @bopen_tmp_file() is the best way how to come to a temporary file. * However, in some specific cases you can need more, so there is also a set * of more general functions. ***/ @@ -207,8 +207,8 @@ int open_tmp(char *name_buf, int open_flags, int mode); /** * Sometimes, a file is created as temporary and then moved to a stable - * location. This function takes a fastbuf created by bopen_tmp_file() - * or bopen_tmp(), marks it as permanent, closes it and renames it to + * location. This function takes a fastbuf created by @bopen_tmp_file() + * or @bopen_tmp(), marks it as permanent, closes it and renames it to * @name. * * Please note that it assumes that the temporary file and the @name @@ -245,8 +245,8 @@ struct fastbuf *bopen_limited_fd(int fd, uns bufsize, uns limit); /** Create a f * in memory (as a linked list of memory blocks, so address space * fragmentation is avoided). * - * First, you use fbmem_create() to create the stream and the fastbuf - * used for writing to it. Then you can call fbmem_clone_read() to get + * First, you use @fbmem_create() to create the stream and the fastbuf + * used for writing to it. Then you can call @fbmem_clone_read() to get * an arbitrary number of fastbuf for reading from the stream. ***/ @@ -267,7 +267,7 @@ struct fastbuf *fbmem_clone_read(struct fastbuf *f); /** Given a writing fastbuf * * In some cases, the front-ends can take advantage of rewriting the contents * of the buffer temporarily. In this case, set @can_overwrite as described - * in xref:internal[Internals]. If you do not care, keep @can_overwrite zero. + * in <>. If you do not care, keep @can_overwrite zero. * * It is not possible to close this fastbuf. */ @@ -278,7 +278,7 @@ void fbbuf_init_read(struct fastbuf *f, byte *buffer, uns size, uns can_overwrit * The fastbuf structure is allocated by the caller and pointed to by @f. * An attempt to write behind the end of the buffer dies. * - * Data are written directly into the buffer, so it is not necessary to call bflush() + * Data are written directly into the buffer, so it is not necessary to call @bflush() * at any moment. * * It is not possible to close this fastbuf. @@ -294,7 +294,7 @@ static inline uns fbbuf_count_written(struct fastbuf *f) /** Calculates, how man * === Fastbuf on recyclable growing buffers [[fbgrow]] * * The `fbgrow` back-end keeps the stream in a contiguous buffer stored in the - * main memory, but unlike xref:fbmem[`fbmem`], the buffer does not have a fixed + * main memory, but unlike <>, the buffer does not have a fixed * size and it is expanded to accomodate all data. * * At every moment, you can use `fastbuf->buffer` to gain access to the stream. @@ -322,13 +322,13 @@ struct fbpool { /** Structure for fastbufs & mempools. **/ **/ void fbpool_init(struct fbpool *fb); /** Initialize a new mempool fastbuf. **/ /** - * Start a new continuous block and prepare for writing (see mp_start()). + * Start a new continuous block and prepare for writing (see <>). * Provide the memory pool you want to use for this block as @mp. **/ void fbpool_start(struct fbpool *fb, struct mempool *mp, uns init_size); /** - * Close the block and return the address of its start (see mp_end()). - * The length can be determined by calling mp_size(mp, ptr). + * Close the block and return the address of its start (see <>). + * The length can be determined by calling <>. **/ void *fbpool_end(struct fbpool *fb); @@ -371,7 +371,7 @@ struct fb_atomic { * If the file has fixed record length, just set @record_len to it. * Otherwise set @record_len to the expected maximum record length * with a negative sign (you need not fit in this length, but as long - * as you do, the fastbuf is more efficient) and call fbatomic_commit() + * as you do, the fastbuf is more efficient) and call @fbatomic_commit() * after each record. * * You can specify @record_len, if it is known (for optimisations). @@ -404,11 +404,11 @@ int bconfig(struct fastbuf *f, uns type, int data); /** Configure a fastbuf. Ret /** * Close and free fastbuf. - * Can not be used for fastbufs not returned from function (initialized in a parameter, for example the one from +fbbuf_init_read+). + * Can not be used for fastbufs not returned from function (initialized in a parameter, for example the one from `fbbuf_init_read`). */ void bclose(struct fastbuf *f); void bflush(struct fastbuf *f); /** Write data (if it makes any sense, do not use for in-memory buffers). **/ -void bseek(struct fastbuf *f, ucw_off_t pos, int whence); /** Seek in the buffer. See +man fseek+ for description of @whence. Only for seekable fastbufs. **/ +void bseek(struct fastbuf *f, ucw_off_t pos, int whence); /** Seek in the buffer. See `man fseek` for description of @whence. Only for seekable fastbufs. **/ void bsetpos(struct fastbuf *f, ucw_off_t pos); /** Set position to @pos bytes from beginning. Only for seekable fastbufs. **/ void brewind(struct fastbuf *f); /** Go to the beginning of the fastbuf. Only for seekable ones. **/ ucw_off_t bfilesize(struct fastbuf *f); /** How large is the file? -1 if not seekable. **/ @@ -502,12 +502,12 @@ static inline void bwrite(struct fastbuf *f, const void *b, uns l) /** Writes bu } /** - * Reads a line into @b and strips trailing +\n+. - * Returns pointer to the terminating 0 or +NULL+ on EOF. + * Reads a line into @b and strips trailing `\n`. + * Returns pointer to the terminating 0 or NULL on `EOF`. * Dies if the line is longer than @l. **/ char *bgets(struct fastbuf *f, char *b, uns l); -char *bgets0(struct fastbuf *f, char *b, uns l); /** The same as bgets(), but for 0-terminated strings. **/ +char *bgets0(struct fastbuf *f, char *b, uns l); /** The same as @bgets(), but for 0-terminated strings. **/ /** * Returns either length of read string (excluding the terminator) or -1 if it is too long. * In such cases exactly @l bytes are read. @@ -517,12 +517,12 @@ int bgets_nodie(struct fastbuf *f, char *b, uns l); struct mempool; struct bb_t; /** - * Read a string, strip the trailing +\n+ and store it into growing buffer @b. + * Read a string, strip the trailing `\n` and store it into growing buffer @b. * Dies if the line is longer than @limit. **/ uns bgets_bb(struct fastbuf *f, struct bb_t *b, uns limit); /** - * Read a string, strip the trailing +\n+ and store it into buffer allocated from a memory pool. + * Read a string, strip the trailing `\n` and store it into buffer allocated from a memory pool. **/ char *bgets_mp(struct fastbuf *f, struct mempool *mp); @@ -535,13 +535,13 @@ void bgets_stk_init(struct bgets_stk_struct *s); void bgets_stk_step(struct bgets_stk_struct *s); /** - * Read a string, strip the trailing +\n+ and store it on the stack (allocated using alloca()). + * Read a string, strip the trailing `\n` and store it on the stack (allocated using alloca()). **/ #define bgets_stk(fb) \ ({ struct bgets_stk_struct _s; _s.f = (fb); for (bgets_stk_init(&_s); _s.cur_len; _s.cur_buf = alloca(_s.cur_len), bgets_stk_step(&_s)); _s.cur_buf; }) /** - * Write a string, without 0 or +\n+ at the end. + * Write a string, without 0 or `\n` at the end. **/ static inline void bputs(struct fastbuf *f, const char *b) { @@ -568,6 +568,7 @@ static inline void bputsn(struct fastbuf *f, const char *b) void bbcopy_slow(struct fastbuf *f, struct fastbuf *t, uns l); /** * Copy @l bytes of data from fastbuf @f to fastbuf @t. + * `UINT_MAX` means all data, even if more than `UINT_MAX` bytes remain. **/ static inline void bbcopy(struct fastbuf *f, struct fastbuf *t, uns l) {