drain

drain( 
[ p_outputPort ] 
) 
=> t / nil

Description

Writes out all characters that are in the output buffer of a port.

Analogous to fflush in C (plus fsync if the port is a file). Not all systems guarantee that the disk is updated on each write. As a result, it is possible for a set of seemingly successful writes to fail when the port is closed.

To protect your data, call drain after a logical set of writes to a file port. It is not recommended that you call drain after every write however, because this could impact your program's performance.

Arguments

p_outputPort

Port to flush output from. If no argument is given this function does nothing.

Value Returned

t	If all buffered data was successfully written out.
nil	There was a problem writing out the data, and some or all of it was not successfully written out.
	Signals an error if the port to be drained is an input port or has been closed.

Examples

drain()          
=> t

drain(poport)    
=> t

myPort = outfile("/tmp/myfile")
=> port:"/tmp/myfile"

for(i 0 15 fprintf(myPort "Test output%d\n" i))
=> t

system( "ls -l /tmp/myfile")
--rw-r--r-- 1 root 0 Aug12 14:44 /tmp/myFile
fileLength( "/tmp/myfile")
=> 0

drain(myPort)
=> t

fileLength( "/tmp/myfile" )
=> 230

close(myPort)
=> t

drain(myPort)
=> *Error* drain: cannot send output to a closed port - port:
        "/tmp/myfile"

drain(piport)
=> *Error* drain: cannot send output to an input port - 
      port:"*stdin*"

drain(poport)
=> t

defun(handleWriteError (x) 
   printf("WARNING - %L write unsuccessful\n" x) nil)
=> handleWriteError

myPort=outfile("/tmp/myfile")
=> port:"/tmp/myfile"

for(i 0 15 fprintf(myPort "%d\n" (2**i)))
=> t

if(!drain(myPort) handleWriteError(myPort) t)
=> t

Related Topics

outfile

close

Return to top