Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management. Open link

fopen()

Open a PSL channel to a file. 

Syntax

fopen(filename,mode)

Parameters

Parameter

Definition

filename

name of the file to which the PSL channel should be opened.

mode

file access mode*Valid Values* 
r open for read 
w truncate to zero length for write or create file for write 
a open for append to end of file or create for write 
rb open binary file for read 
wb truncate binary file to zero length for write or create binary file for write 
ab open binary file for append at end of file or create binary file for write 
r+ open for read and write (update) 
w+ truncate to zero length for read and write or create for read and write 
a+ open for read and write at end of file or create file for read and write 
r+b open binary file for read and write (update) 
w+b truncate binary file to zero length for read and write or create binary file for read and write 
a+b open binary file for read and write at end of file or create binary file for read and write

Description

The fopen() function opens a channel to filename that provides the access to filename from within a PSL process. Theread()readln()write()get_chan_info()share()fseek()ftell(), and close() functions apply to channels that have been opened to files. 

When supported by the underlying operating system, the fopen() function performs security checks to determine whether the user name of the calling process has permission for the request. The valid range of mode is the same as for the ANSI Cfopen() function. 

If the fopen() function is successful, it returns the PSL channel number to filename. A failure to open filename, such as an operating system problem or invalid mode, sets the PSL errno value and causes the fopen() function to return the NULL string without attempting to open the file. The fopen() function behaves much like the ANSI C fopen() function.

File Permission Changes Using Mode a or w

When the target system is running a variant of Unix, opening filename using mode a or w (append or write) will changefilename permissions and ownership to be those of the user name of the calling process. The change uses the Unix chmodand chown commands. The new filename permission value is 0644 octal, which is read/write for the process user name and read permission for all other users. 

When the target system is non-Unix, the file permission changes depend on whether the underlying file system supports the concept of a file owner. If it does, then file ownership is set to the user name of the calling process and write access is restricted to the owner. If it does not, the file will be accessible by any user.

Support for Binary File Access

The fopen() function permits binary modes with a b character, though there is currently no way within a PSL process to write any form of binary data other than character strings. The fopen() function b mode may be useful on some non-Unix platforms to prevent the conversion of CR/LF pairs back and forth to new-line characters, as performed by some standard C libraries for text files.

Using the fopen Function with the fseek Function

The fseek() function may not be meaningful for text files on some non-Unix platforms, so specifying {} in mode may imply bregardless of whether b is specified. BMC Software recommends that you use the {} in mode for the fopen() function whenever you require file positioning using the PSL fseek() function.

Flush a File after Each PSL File Operation

The PSL functions ensure that a file is flushed after every operation so that the well-known bug of doing a write-then-read or read-then-write without an intervening fseek rewind or fflush does not occur in PSL file operations.

fopen() Function and Named Pipes

Do not use the fopen() function to open named pipes (FIFOs). Doing so will cause the PATROL Agent to block indefinitely. Instead, use the following popen() function to open a channel for reading to the read_fifo shell script:

popen("OS","read_fifo fifo");

Where fifo is the name of the named pipe you wish to open, and read_fifo is the following shell script:

#!/bin/sh
#
# read_fifo <fifo>
#
while [ 1 ]; do
if [ ! -p $1 ]; then
cat <<- EOF
cannot open '$1' -- no such file
EOF
exit 1
cat $1
done

You can use the channel number returned by the popen() function as an argument in the read() or readln() functions to retrieve the information the read_fifo shell script has read from the named pipe.

Example

The following fopen() function call shows different modes for opening a file:

# open a file for reading
readchan = fopen("/etc/passwd","r");
# open a file for writing
writechan = fopen("/tmp/abc123","w");
# open a file for appending
appendchan = fopen("tmp/newtmp123","a");


Was this page helpful? Yes No Submitting... Thank you

Comments