handler procedure type

If you do not supply the handler-type attribute, your handler procedure must be the default type. The profile of the procedure must be:

int my_handler(char const * pz_entry);

However, if you do supply this attribute, you may set the value to any of four alternate flavors:

‘name-of-file’

This is essentially the same as the default handler type, except that before your procedure is invoked, the generated code has verified that the string names an existing file. The profile is unchanged.

‘file-X’

Before calling your procedure, the file is f-opened according to the X, where X may be any of the legal modes for fopen(3C). In this case, the profile for your procedure must be:

int my_handler(char const * pz_fname, FILE * entry_fp);

When processing inputs as file pointer stream files, there are several ways of treating standard input. It may be an ordinary input file, or it may contain a list of files to operate on.

If the file handler type is more specifically set to ‘file-r’ and a command line operand consists of a single hyphen, then my_handler will be called with entry_fp set to stdin and the pz_fname set to the translatable string, "standard input". Consequently, in this case, if the input list is being read from stdin, a line containing a hyphen by itself will be ignored.

‘stdin-input’

This attribute specifies that standard input is a data input file. By default, for-each main procedures will read standard input for operands if no operands appear on the command line. If there are operands after the command line options, then standard input is typically ignored. It can always be processed as an input data file, however, if a single bare hyphen is put on the command line.

‘text-of-file’

‘some-text-of-file’

Before calling your procedure, the contents of the file are read or mapped into memory. (Excessively large files may cause problems.) The ‘some-text-of-file’ disallows empty files. Both require regular files. In this case, the profile for your procedure must be:

program_exit_code_t my_handler(char const * fname, char * file_text, size_t text_size);

Note that though the file_text is not const, any changes made to it are not written back to the original file. It is merely a memory image of the file contents. Also, the memory allocated to hold the text is text_size + 1 bytes long and the final byte is always NUL. The file contents need not be text, as the data are read with the read(2) system call.

file_text is automatically freed, unless you specify a handler-frees attribute. Then your code must free(3) the text.

If you select one of these file type handlers, then on access or usage errors the PROGRAM_EXIT_FAILURE exit code will, by default, be or-ed into the final exit code. This can be changed by specifying the global file-fail-code attribute and naming a different value. That is, something other than failure. You may choose success, in which case file access issues will not affect the exit code and the error message will not be printed.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.