*
* 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:
*
* 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.
*
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 */
* 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. **/
* 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.
***/
/**
* 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
* 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.
***/
*
* 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 <<internal,Internals>>. If you do not care, keep @can_overwrite zero.
*
* It is not possible to close this fastbuf.
*/
* 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.
* === 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 <<fbmem,`fbmem`>>, 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.
**/
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 <<mempool:mp_start()>>).
* 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 <<mempool:mp_end()>>).
+ * The length can be determined by calling <<mempool:mp_size(mp, ptr)>>.
**/
void *fbpool_end(struct fbpool *fb);
* 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).
/**
* 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. **/
}
/**
- * 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.
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);
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)
{
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)
{
projects / libucw.git / blobdiff