balst_resolver_filehelper

Provide platform-independent file input for stack trace resolvers.

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

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,
                 FilesystemUtil::e_OPEN_OR_CREATE,  // doesn't already exist
                 FilesystemUtil::e_READ_WRITE);     // writable
 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;
     rc = helper.openFile(fileNameBuffer);
     assert(0 == rc);
 
     char buf[100];    Span bufSpan(buf);
     memset(buf, 0, sizeof(buf));
     rc = helper.readExact(Span(buf, 6),
                           128);                 // offset
     assert(0 == rc);
     assert(!strcmp(buf, "abcdef"));

readExact past EOF fails

     rc = helper.readExact(Span(buf, 6),
                           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));
     bsl::string_view result = helper.loadString(buf,
                                                 OFFSET_OF_ZERO_BYTE - 12);
     assert(12 == result.length());
     assert("0123456789+-" == result);
 }
 bdls::FilesystemUtil::remove(fileNameBuffer);