version 1.3, 2010/06/27 15:52:41 |
version 1.5, 2010/07/04 22:04:04 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.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 145 Returns 0 on failure, 1 on success. |
|
Line 155 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 |
|
|
.Nm |
.Nm |
library was written by |
library was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
|
.Sh BUGS |
|
The implementation of user-defined strings needs improvement: |
|
.Bl -dash |
|
.It |
|
String values are taken literally and are not interpreted. |
|
.It |
|
Parsing of quoted strings is incomplete. |
|
.It |
|
The stings are stored internally using a singly linked list, |
|
which is fine for small numbers of strings, |
|
but ineffient when handling many strings. |
|
.El |