How does the startFileName parameter work on the b2_list file_names API?

Let's say you have the following folder structure in a bucket

cats/
  photo1.jpg
  photo2.jpg
kittens/
  video1.jpg
  video2.jpg
cats-readme.txt

If you want to get the files and folder structure at the level "cats"
the startFileName prefix should be "cats/"

If you wanted to get the file and folder structure at the level "kittens"
the startFileName prefix should be "cats/kittens/"

The trailing slash is important. Without it, the first file in the list to be returned out be cats-readme.txt, not cat/photo1.jpg.

For each bucket, B2 internally keeps an alphabetically sorted list of the files in that bucket. When you specify a startFileName, it gives you that file and the next 1000 files (of the number given to maxFileCount).

The folder structure example above would be returned by b2_list_file_names in this alphabetical order:

cats-readme.txt
cats/photo1.jpg
cats/photo2.jpg
kittens/video1.jpg
kittens/video2.jpg