Next: code for handler procedure, Previous: procedure to handle each argument, Up: Generating main procedures [Contents][Index]
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
, whereX
may be any of the legal modes forfopen(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 tostdin
and thepz_fname
set to the translatable string, "standard input". Consequently, in this case, if the input list is being read fromstdin
, 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 notconst
, 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 istext_size + 1
bytes long and the final byte is alwaysNUL
. The file contents need not be text, as the data are read with theread(2)
system call.file_text
is automatically freed, unless you specify ahandler-frees
attribute. Then your code mustfree(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.