Stream must be a currently open file containing lines previously sorted in increasing order by the simple numeric values of the characters.
Pattern must be a valid pointer to char. A nil pattern (e.g. *pattern == 0) matches anything, so bsearchstr returns zero (start of file) in this case. A nil line in the file (e.g. nothing but a newline) is treated as being less than any non-nil pattern.
If caseins is zero, searching is done case-sensitively, and the data file should be sorted accordingly. If caseins is non-zero, searching is done case-insensitively, and the data must have been sorted using "sort -f" or equivalent. The routine uses malloc(3) to get memory to make an uppercased copy of pattern, so as not to modify the passed-in value.
If tellnext is zero, and no line in the file begins with pattern, bsearchstr returns -1. If tellnext is non-zero, it returns the offset of the first line lexically after pattern. It returns the size of the file if the last line is before pattern.
Each time bsearchstr halves the remainder of the file, it seeks to a location which is usually not the start of a line. It searches forwards, then backwards, a character at a time, to locate the next start of line. This is normally more efficient than linear searching the file, especially if the file is large and no lines are extremely long. Also, bsearchstr works fine even if the last line in the file is not terminated by a newline.
Returns -2 if any fseek(3s), ftell(3s), or malloc(3c) error occurs. In this case the current file location is unpredictable.