tbl
Purpose
Performs operations on table files.
Library
Security Library (libs.a)
Syntax
#include <paths.h>
#include <tbl.h>
int tblgetrec (file, key, fnum, ftypint tblgetfield (recbuf, fnum, fieldbuf )
recbuf, bufsize) char *recbuf;
char *file, *key; int fnum;
int fnum; char *fieldbuf;
enum fld_type ftype;
char recbuf[ ]; int tblsetfield (recbuf, fnum, newfield)
int bufsize; char *recbuf;
int fnum;
int tblsetrec (file, cmd, kfnum, kftchar *newfield;
recbuf)
char *file; int tblgetline (fd, buf, bufsize)
enum setreccmd cmd; int fd;
int kfnum; char *buf;
enum fld_type kftype; int bufsize;
char recbuf[ ];
Description
The table file subroutines perform management tasks on
table file records and fields. A table file is a styl-
ized text file with newline-terminated lines, where each
line is either a comment line, a blank line, or a record
line. A comment line has a # character as its first
character. A blank line contains zero or more space or
tab characters followed by a newline character. A record
line (or entry) contains one or more colon-separated
fields, where a field is a sequence of characters, none
of which is a colon or a newline.
The tblgetrec subroutine searches the specified table
file for the topmost record that matches key in the spec-
ified field. Comment lines and blank lines are skipped.
The parameters contain the following:
file Table file name.
key Key string to identify the desire record.
fnum Field number, where field numbers are zero-based.
ftype Type of field: string or integer.
recbuf Caller-allocated buffer for the found record.
bufsize Size of recbuf.
The tblgetrec subroutine opens, searches, then closes the
given file. The maximum record size, the maximum field
size, and the maximum number of fields per record in a
table file, respectively, are defined in the tbl.h header
file as TBL_RECSIZE, TBL_FIELDSIZE, and TBL_MAXFIELDS.
The tblgetrec subroutine does not lock the file that it
searches.
For example, the program schema to search the password
file for the record corresponding to user name "root" is:
#include <paths.h>
#include <tbl.h>
...
char rec[TBL_RECSIZE|;
...
if ( tblgetrec (PATH_PASSWD, "root", (int)PASS_NAME,
TBL_T_STRING, rec, TBL_RECSIZE) != 1 )
[
...
]
The tblsetrec subroutine performs a simple update to a
table file. The parameters for this subroutine are:
file Contains the table file name to update.
cmd Specifies the type of update to perform, from one
of the following:
TBL_REPLACE Replaces a record.
TBL_DELETE Deletes a record.
TBL_APPEND Appends a record.
kfnum Specifies, for replace or delete operations, the
field number of the key.
kftype Specifies, for replace or delete operations, the
field type of the key.
recbuf Contains in the kfnum field for replace or delete
operations, the key to update. For replace or
append operations, recbuf contains the new
record.
To change the key field of a record, you must delete the
record first, then append the new record.
The tblsetrec subroutine uses update-in-place (which pre-
serves the same file i-node) to update the file and keeps
a backup version of the file on the same node. If f is
the name of the file, then f- is the name of the backup
version. File f+ is a temporary working file that the
tblsetrec subroutine removes once execution is completed.
The tblgetfield subroutine copies field fnum, a zero-
based field number, from the input record buffer recbuf
to the output field buffer fieldbuf. The tblgetfield
subroutine assumes that the fieldbuf parameter is big
enough to hold the null-terminated string it will
receive.
The tblsetfield subroutine replaces the value of field
fnum, a zero-based field number, in record recbuf with
value newfield. Since the recbuf parameter now contains
the new record, recbuf is both an input and output param-
eter. The tblsetfield subroutine assumes that parameter
recbuf is big enough to hold the null-terminated string
it will receive.
The tblgetline subroutine reads a line from a table file,
and returns that line with the newline character replaced
by a NULL. The fd parameter is the file descriptor of
the already open table file, the buf parameter receives
the line, and the bufsize parameter is the size of buf.
Return Value
Upon successful completion, the tblgetrec subroutine
returns a value of 1, and the recbuf parameter holds the
found record. If tblgetrec fails, it returns one of the
following values:
0 Record was not found.
-1 Cannot open file.
-2 Buffer overflow occurred.
The tblsetrec subroutine returns 0 for record to replace
or delete not found, 1 for updated, and the following
negative numbers for failure:
-1 Cannot open file.
-2 Cannot lock file.
-3 Cannot stat file.
-4 Files file and file- are on different nodes.
-5 Cannot create file.
-6 Caught interrupt while updating file.
The tblgetfield subroutine returns 0 for success and -1
for failure (no such field).
The tblsetfield subroutine returns 0 for success and -1
for failure when the fnum parameter is less than 0 or
greater than TBL_MAXFIELDS.
The tblgetline subroutine returns the number of bytes
read upon successful completion. On failure, tblgetline
returns one of the following values:
-1 End of file reached.
-2 buf is too small.
-3 For error.
Files
f current version
f- backup version
f working version (temporary file)
Related Information
In this book: "getgrent, getgrgid, getgrnam, setgrent,
endgrent" and "getpwent, getpwuid, getpwnam, setpwent,
endpwent."