balst_resolver_filehelper

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage

Purpose

Provide platform-independent file input for stack trace resolvers.

Classes

• balst::Resolver_FileHelper: file input for stack trace resolvers

See also

balst_resolverimpl_elf, balst_resolverimpl_xcoff

Description

The one class in this component opens a file in readonly mode and then owns the file descriptor, and provides 3 utility functions for reading from the file: readBytes, which attempts to read a number of bytes into a buffer, and does a partial read if it can't read that many; readExact, which either reads an exact number of bytes or fails, and loadString, which reads a 0 terminated string from the file, copies it to a buffer it allocates, and returns a pointer to the copy.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

First, we prepare the file to be used by this usage example:

bslma::TestAllocator ta;
 
char fileNameBuffer[100];
sprintf(fileNameBuffer,
        "/tmp/balst_Resolver_FileHelper.usage.%d.txt",
        getProcessId());

Make sure file does not already exist.

bdls::FilesystemUtil::remove(fileNameBuffer);

Next, create the file and open a file descriptor to it. The boolean flags indicate that the file is writable, and not previously existing (and therefore must be created).

FdType fd = FilesystemUtil::open(fileNameBuffer,
                           true,          // writable
                           false);        // doesn't already exist
assert(FilesystemUtil::k_INVALID_FD != fd);

64 char long string

const char *testString64 =
            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
                                                    "0123456789+-";

Populate the file with known data, with a zero byte at a known offset.

int rc;
for (int i = 0; i < 20; ++i) {
    rc = FilesystemUtil::write(fd, testString64, 64);
    assert(64 == rc);
}
 
enum { OFFSET_OF_ZERO_BYTE = 7 * 64 };
 
rc = (int) FilesystemUtil::seek(fd,
                          OFFSET_OF_ZERO_BYTE,
                          FilesystemUtil::e_SEEK_FROM_BEGINNING);
assert(OFFSET_OF_ZERO_BYTE == rc);
 
rc = FilesystemUtil::write(fd, "", 1);        // write the zero byte
assert(1 == rc);
 
rc = FilesystemUtil::close(fd);
assert(0 == rc);
 
{
    balst::Resolver_FileHelper helper(fileNameBuffer);
 
    char buf[100];
    memset(buf, 0, sizeof(buf));
    rc = helper.readExact(buf,
                          6,                    // # chars to read
                          128);                 // offset
    assert(0 == rc);
    assert(!strcmp(buf, "abcdef"));

readExact past EOF fails

    rc = helper.readExact(buf,
                          6,                    // # chars to read
                          64 * 40);             // offset
    assert(0 != rc);

loadString will read a zero terminated string at a given offset, using a buffer passed in, and allocating memory for a new copy of the string.

    memset(buf, 'a', sizeof(buf));
    char *result = helper.loadString(OFFSET_OF_ZERO_BYTE - 12,
                                     buf,
                                     sizeof(buf),
                                     &ta);
 
    assert(12 == bsl::strlen(result));
    assert(!bsl::strcmp("0123456789+-", result));

clean up

    ta.deallocate(result);
}
bdls::FilesystemUtil::remove(fileNameBuffer);