getbootpent(3X)

NAME

getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() — get or put bootptab entry

SYNOPSIS

#include <bootpent.h>

int getbootpent (struct bootpent **bootpent);

int setbootpent (const char *path);

int endbootpent (void);

int putbootpent ( 
     struct bootpent *bootpent, 
     int numfields, 
     FILE * bootpfile 
); 

int parse_bp_htype (const char *source);

int parse_bp_haddr ( 
     char **source, 
     int htype, 
     unsigned char *result, 
     unsigned int *bytes 
); 

int parse_bp_iaddr ( 
     char **source, 
     unsigned long *result 
); 

Remarks

These functions reside in libdc.a, and are linked using the -ldc option to the ld or cc command.

DESCRIPTION

These functions help a program read or modify a bootptab (bootpd control) file one entry at a time. getbootpent() locates an entry in the /etc/bootptab file, or an alternate file specified to setbootpent(), and returns a pointer to an array of objects of type struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines.

The bootpent structure is defined in <bootpent.h> and includes the following members:

int   bp_type;   /* BP_DATA, BP_COMMENT, BP_BLANK  */ 
char  *bp_text;  /* one field or one comment line  */ 

The file also defines the following data type and constants:

typedef struct bootpent *bpp_t; 

#define BP_NULLP  ((bpp_t) 0) 
#define BP_SIZE   (sizeof (struct bootpent)) 

#define MAXHADDRLEN         6 

#define HTYPE_UNKNOWN       0   /* 0 bytes  */ 
#define HTYPE_ETHERNET      1   /* 6 bytes  */ 
#define HTYPE_EXP_ETHERNET  2   /* 1 byte   */ 
#define HTYPE_AX25          3   /* 0 bytes  */ 
#define HTYPE_PRONET        4   /* 1 byte   */ 
#define HTYPE_CHAOS         5   /* 0 bytes  */ 
#define HTYPE_IEEE802       6   /* 6 bytes  */ 
#define HTYPE_ARCNET        7   /* 0 bytes  */ 

#define MAXHTYPES           7 

The fields are described in the Field Definitions section below. The purpose of each function is as follows.

getbootpent()

When first called, getbootpent() returns a pointer to, and the number of elements in, an array of bootpent structures. The array holds the first entry in the /etc/bootptab file (or from an alternate file specified by a call to setbootpent()), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file.

If no file is currently in memory, getbootpent() reads the /etc/bootptab file prior to doing its work.

The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in EXAMPLES below. The data remains valid until the next call of setbootpent() or endbootpent().

If there are comments after the last entry, they are returned as a separate entry with no data parts.

setbootpent()

Opens the specified file for reading by getbootpent(), reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see lockf(2)). If the given path is a null pointer or a null string, setbootpent() opens and reads /etc/bootptab.

If the last file opened by setbootpent() (or implicitly by getbootpent()) was /etc/bootptab, a subsequent call to setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to endbootpent().

endbootpent()

Frees the in-memory copy of the last file opened by setbootpent(), or getbootpent().

putbootpent()

Writes (to the current location in the stream specified by bootpfile) the ASCII equivalent of the specified array of bootpent structures containing one file entry, and its leading, or embedded, comments (a total of numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\''. If numfields is less than or equal to zero, nothing is written.

parse_bp_htype()

Converts a host address type from string to numeric format (HTYPE_*) in the same manner as bootpd.

parse_bp_haddr()

Converts a host (hardware, link level) address from string to binary format in the same manner as bootpd given a host address type (HTYPE_*). The calling program's result, which must be an array containing at least MAXHADDRLEN elements, is modified to hold the host address binary value, and bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. source is modified to point to the first char after the parsed address.

parse_bp_iaddr()

Converts an internet address from string to binary format in the same manner as bootpd. This can be used to compare two internet addresses, independent of string representations. The calling program's result is modified to hold the internet address binary value. source is modified to point to the first char after the parsed address.

Field Definitions

If bootpent.bp_type is BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned.

If bootpent.bp_type is BP_COMMENT or BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline.

The returned array elements are in the same order as data fields and comment lines appear in the file.

Entry field strings are of the form:

tag[@][="value"] 

with surrounding whitespace, if any, removed (see bootpd(1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings.

Template entries (those referred to by other entries using tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, tc fields, and ``@'' fields that override earlier field values.

RETURN VALUE

getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns -1. If it encounters a memory allocation or map error, or a read error, it returns -2.

setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns -1. If it encounters a memory allocation or map error or a read error it returns -2.

endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns -1. If it cannot free the memory for the current file it returns -2.

putbootpent() returns zero if successful writing an entry to the specified file, with the ferror() indication clear (see ferror(3S)). Otherwise it returns non-zero with ferror() set.

In all cases above, if a failure is due to a failed system call, the errno value from the system is valid on return from the called function.

parse_bp_htype() returns HTYPE_UNKNOWN if the hardware type string is unrecognized.

parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid htype, or a host address type for which the address length is unknown; source is modified to point to the first illegal char (a NUL if the string is too short). The caller's bytes value is unmodified, but result might be changed.

parse_bp_iaddr() returns zero if successful, otherwise non-zero, and source is modified to point to the first illegal char (a NUL if the string is null).

EXAMPLES

The following code fragment copies all data and comments from /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line).

#include <bootpent.h>

FILE *newfilep;   /* to write temp file */
bpp_t bp;         /* read from file */
int field;        /* current field number */
int fields;       /* total in array for one entry */

if ((newfilep = fopen ("/tmp/bootptab", "w")) == (FILE *) NULL)
{
    (handle error)
}

while ((fields = getbootpent (&bp)) > 0)
{
    for (field = 0; field < fields; ++field)
    {
        if ((bp[field].bp_type) == BP_DATA)
        {
            (void) puts (bp[field].bp_text);
            break;
        }
    }

    if (putbootpent (bp, fields, newfilep))
    {
        (handle error)
    }
}

if (fields < 0)    /* error reading file */
{
    (handle error)
}

if (endbootpent())
{
    (handle error)
}

if (fclose (newfilep))
{
    (handle error)
}

The following code fragment saves a copy of a bootptab entry returned by getbootpent().

#include <malloc.h>
#include <string.h>
#include <bootpent.h>

bpp_t bpnew;
unsigned size;

size = fields *BP_SIZE;

if ((bpnew = (bpp_t) malloc (size)) == BP_NULLP)
{
    (handle error)
}

(void) memcpy ((void *)bpnew, (void *)bp, size);

WARNINGS

These functions are unsafe in multi-thread applications.

Calling setbootpent() releases any locks on the file it opens.

AUTHOR

These functions were developed by HP.

FILES

/etc/bootptab: control file for bootpd