Message file access: Reading message data

Modify message contents by reading from open file handles. Reading data from a file directly into a message object preserves any null characters embedded in the data. The file-read commands neither have nor require the -cvtnull option.

Message objects support three styles of reading:

  • nl (newline-terminated) reads up to, discards, the next newline character. This style is identical to that supported by the File protocol driver.

    Use this style to assign a line of input text to a message.

    For example:

    Input: msgread nl message6 stdin\
    This is user input
    Output: 18
    Input: msgget message6
    Output: This is user input 
  • len10 (10-byte length-encoded) treats the next 10 characters in the file as a 10-digit ASCII representation of the number of characters in the message itself. This style is identical to that supported by the File protocol driver.
  • raw reads the user-specified number of characters to read.

    When using this style, assume direct control of the number of bytes read.

    Monitor file reads more closely with the -stats option.

    When the -stats option is used and a variable name is supplied as its argument, the variable is assigned a list of two elements: todo done.

    • todo is 0 for nl read, the number of bytes in the len10 header, or the number of bytes requested in a raw read.
    • done is the actual number of bytes read.

    Comparing these values after a failed read can give some insight into the nature of the failure.

    For example:

    Input: open /etc/passwd r
    Output: file4
    
    Input: msgread -stats s nl message6 file4
    Output: 22
    
    Input: echo $s
    Output: 0 22
    
    Input: msgread -stats s raw message6 file4 6
    Output: 6
    
    Input: msgget message6
    Output: daemon
    
    Input: echo $s
    Output: 6 6

No matter which style is used, these commands return the number of bytes read.

All of the file-reading commands operate on open file handles.

This table shows the file-read commands and their comparable message modification commands:

File-read command Message modification command
msgappread msgappend
msginsread msginsert
msgread msgset