version 1.5, 2010/07/04 22:04:04 |
version 1.6, 2010/07/07 15:04:54 |
|
|
.Nd roff macro compiler library |
.Nd roff macro compiler library |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.In mandoc.h |
.In mandoc.h |
.In regs.h |
|
.In roff.h |
.In roff.h |
.Ft "struct roff *" |
.Ft "struct roff *" |
.Fo roff_alloc |
.Fo roff_alloc |
|
|
.Fc |
.Fc |
.Ft void |
.Ft void |
.Fn roff_reset "struct roff *roff" |
.Fn roff_reset "struct roff *roff" |
.In regs.h |
|
.Ft "char *" |
|
.Fn roff_setstr "const char *name" "const char *string" |
|
.Ft "char *" |
|
.Fn roff_getstr "const char *name" |
|
.Ft "char *" |
|
.Fn roff_getstrn "const char *name" "size_t len" |
|
.Ft void |
|
.Fn roff_freestr void |
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
Line 155 Returns 0 on failure, 1 on success. |
|
Line 145 Returns 0 on failure, 1 on success. |
|
Signals that the parse is complete. |
Signals that the parse is complete. |
Returns 0 on failure, 1 on success. |
Returns 0 on failure, 1 on success. |
.El |
.El |
.Sh USER-DEFINED STRINGS |
|
Strings defined by the |
|
.Xr roff 7 |
|
.Sx \&ds |
|
instruction are saved using the |
|
.Fn roff_setstr |
|
function and retrieved using the |
|
.Fn roff_getstr |
|
and |
|
.Fn roff_getstrn |
|
functions. |
|
.Pp |
|
These functions take the name of the string to be accessed |
|
as their first argument. |
|
While |
|
.Fn roff_getstr |
|
requires the name to be null-terminated, |
|
.Fn roff_getstrn |
|
accepts non-terminated strings, but requires the length of the name |
|
to be specified. |
|
.Pp |
|
The second argument to |
|
.Fn roff_setstr |
|
is the new value of the string. |
|
It will be copied to internal storage, so both pointers to constant |
|
strings and pointers to volatile storage are acceptable. |
|
.Pp |
|
All of these functions return a pointer to the new value of the string |
|
in internal storage, which should be considered read-only, so use |
|
.Xr strdup 3 |
|
on it as appropriate. |
|
The read functions return NULL when a string of the specified name |
|
is not available or empty, and |
|
.Fn roff_setstr |
|
returns NULL when memory allocation fails. |
|
In the latter case, the string will remain unset. |
|
.Pp |
|
The function |
|
.Fn roff_freestr |
|
clears all user-defined strings. |
|
It always succeeds. |
|
Both |
|
.Fn roff_reset |
|
and |
|
.Fn roff_free |
|
call it. |
|
.Sh EXAMPLES |
.Sh EXAMPLES |
See |
See |
.Pa main.c |
.Pa main.c |