HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Developer's Guide: TAR

» Return to Contents



ocPortal implements TAR support for use by the modification and backup modules, and other modules that wish to draw upon the functionality.
The same goes for ZIP support, although unzipping relies on PHP functions or an 'unzip' program being on the server.

It has been purposely implemented to act in the same way as standard PHP file IO.

sources/tar.php

Global_functions_tar.php

Function summary

array tar_open (PATH path, string mode)
?array tar_get_directory (array resource, boolean tolerate_errors)
integer file_size_to_tar_block_size (integer size)
array tar_add_folder_incremental (array resource, ?resource logfile, PATH path, TIME threshold, ?integer max_size, PATH subpath, boolean all_files)
void tar_add_folder (array resource, ?resource logfile, PATH path, ?integer max_size, PATH subpath, ?array avoid_backing_up, ?array root_only_dirs, boolean tick, boolean all_files)
void tar_extract_to_folder (array resource, PATH path, boolean use_afm, ?array files, boolean comcode_backups)
?array tar_get_file (array resource, PATH path, boolean tolerate_errors, ?PATH write_data_to)
void tar_add_file (array resource, PATH target_path, string data, integer _mode, TIME _mtime, boolean data_is_path)
integer tar_crc (string header)
void tar_close (array resource)

array tar_open(PATH path, string mode)

Open up a TAR archive, and return the resource.

Parameters…

Name path
Description The path to the TAR archive
Type PATH

Name mode
Description The mode to open the TAR archive (rb=read, wb=write)
Type string
Values restricted to rb wb w+b

Returns…

Description The TAR file handle
Type array

Return to the function index for this class Expand: View the source code to this function

?array tar_get_directory(array resource, boolean tolerate_errors)

Return the root directory from the specified TAR file. Note that there are folders in here, and they will end '/'.

Parameters…

Name resource
Description The TAR file handle
Type array

Name tolerate_errors
Description Whether to tolerate errors (returns NULL if error)
Default value boolean-false
Type boolean

Returns…

Description A list of maps that stores 'path', 'mode', 'size' and 'mtime', for each file in the archive (NULL: error)
Type ?array

Return to the function index for this class Expand: View the source code to this function

integer file_size_to_tar_block_size(integer size)

Return the output from the conversion between filesize and TAR block size.

Parameters…

Name size
Description The file size of a file that would be inside the TAR archive
Type integer

Returns…

Description The block size TAR would use to store this file
Type integer

Return to the function index for this class Expand: View the source code to this function

array tar_add_folder_incremental(array resource, ?resource logfile, PATH path, TIME threshold, ?integer max_size, PATH subpath, boolean all_files)

Add a folder to the TAR archive, however only store files modifed after a threshold time. It is incremental (incremental backup), by comparing against a threshold before adding a file (threshold being time of last backup)

Parameters…

Name resource
Description The TAR file handle
Type array

Name logfile
Description The logfile to write to (NULL: no logging)
Type ?resource

Name path
Description The full path to the folder to add
Type PATH

Name threshold
Description The threshold time
Type TIME

Name max_size
Description The maximum file size to add (NULL: no limit)
Type ?integer

Name subpath
Description The subpath relative to the path (should be left as the default '', as this is used for the recursion to distinguish the adding base path from where it's currently looking)
Default value
Type PATH

Name all_files
Description Whether to not skip "special files" (ones not normally archive)
Default value boolean-false
Type boolean

Returns…

Description A list of maps that stores 'path', 'mode' and 'size', for each newly added file in the archive
Type array

Return to the function index for this class Expand: View the source code to this function

void tar_add_folder(array resource, ?resource logfile, PATH path, ?integer max_size, PATH subpath, ?array avoid_backing_up, ?array root_only_dirs, boolean tick, boolean all_files)

Add a folder to the TAR archive

Parameters…

Name resource
Description The TAR file handle
Type array

Name logfile
Description The logfile to write to (NULL: no logging)
Type ?resource

Name path
Description The full path to the folder to add
Type PATH

Name max_size
Description The maximum file size to add (NULL: no limit)
Default value
Type ?integer

Name subpath
Description The subpath relative to the path (should be left as the default '', as this is used for the recursion to distinguish the adding base path from where it's currently looking)
Default value
Type PATH

Name avoid_backing_up
Description A map (filename=>1) of files to not back up (NULL: none)
Default value
Type ?array

Name root_only_dirs
Description A list of directories ONLY to back up from the root (NULL: no restriction)
Default value
Type ?array

Name tick
Description Whether to output spaces as we go to keep the connection alive
Default value boolean-false
Type boolean

Name all_files
Description Whether to not skip "special files" (ones not normally archive)
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

void tar_extract_to_folder(array resource, PATH path, boolean use_afm, ?array files, boolean comcode_backups)

Extract all the files in the specified TAR file to the specified path.

Parameters…

Name resource
Description The TAR file handle
Type array

Name path
Description The full path to the folder to extract to
Type PATH

Name use_afm
Description Whether to extract via the AFM (assumes AFM has been set up prior to this function call)
Default value boolean-false
Type boolean

Name files
Description The files to extract (NULL: all)
Default value
Type ?array

Name comcode_backups
Description Whether to take backups of Comcode pages
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

?array tar_get_file(array resource, PATH path, boolean tolerate_errors, ?PATH write_data_to)

Get the contents of the specified file in the specified TAR.

Parameters…

Name resource
Description The TAR file handle
Type array

Name path
Description The full path to the file we want to get
Type PATH

Name tolerate_errors
Description Whether to tolerate errors (returns NULL if error)
Default value boolean-false
Type boolean

Name write_data_to
Description Write data to here (NULL: return within array)
Default value
Type ?PATH

Returns…

Description A map, containing 'data' (the file), 'size' (the filesize), 'mtime' (the modification timestamp), and 'mode' (the permissions) (NULL: not found / TAR possibly corrupt if we turned tolerate errors on)
Type ?array

Return to the function index for this class Expand: View the source code to this function

void tar_add_file(array resource, PATH target_path, string data, integer _mode, TIME _mtime, boolean data_is_path)

Add a file to the specified TAR file.

Parameters…

Name resource
Description The TAR file handle
Type array

Name target_path
Description The relative path to where we wish to add the file to the archive (including filename)
Type PATH

Name data
Description The data of the file to add
Type string

Name _mode
Description The file mode (permissions)
Type integer

Name _mtime
Description The modification time we wish for our file
Type TIME

Name data_is_path
Description Whether the $data variable is actually a full file path
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

integer tar_crc(string header)

Find the checksum specified in a TAR header

Parameters…

Name header
Description The header from a TAR file
Type string

Returns…

Description The checksum
Type integer

Return to the function index for this class Expand: View the source code to this function

void tar_close(array resource)

Close an open TAR resource.

Parameters…

Name resource
Description The TAR file handle to close
Type array

(No return value)


Return to the function index for this class Expand: View the source code to this function

sources/m_zip.php

Global_functions_m_zip.php

Function summary

void init__m_zip ()
mixed zip_open (PATH zip_file)
boolean zip_close (array open_zip_file)
~array zip_read (array open_zip_file)
PATH _m_zip_RelPath (PATH base_path, PATH path)
boolean zip_entry_open (array zip, array zip_entry, string mode)
boolean zip_entry_close (array zip_entry)
string zip_entry_name (array zip_entry)
integer zip_entry_filesize (array zip_entry)
~string zip_entry_read (array zip_entry, integer zip_entry_file_size)
void m_deldir (PATH a_dir)

void init__m_zip()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

mixed zip_open(PATH zip_file)

Open a zip file for reading.

Parameters…

Name zip_file
Description The zip file path
Type PATH

Returns…

Description The zip file resource (number if error)
Type mixed

Return to the function index for this class Expand: View the source code to this function

boolean zip_close(array open_zip_file)

Close a zip file.

Parameters…

Name open_zip_file
Description The zip file resource
Type array

Returns…

Description Whether the file closed correctly
Type boolean

Return to the function index for this class Expand: View the source code to this function

~array zip_read(array open_zip_file)

Reads the next entry in a zip file archive.

Parameters…

Name open_zip_file
Description The zip file resource
Type array

Returns…

Description A directory entry resource for later use with the m_zip_entry_…() functions (false: if there's no more entries to read).
Type ~array

Return to the function index for this class Expand: View the source code to this function

PATH _m_zip_RelPath(PATH base_path, PATH path)

Make a path relative.

Parameters…

Name base_path
Description The base path (path to make relative to)
Type PATH

Name path
Description The path to make relative
Type PATH

Returns…

Description The relative path
Type PATH

Return to the function index for this class Expand: View the source code to this function

boolean zip_entry_open(array zip, array zip_entry, string mode)

Opens a directory entry in a zip file for reading.

Parameters…

Name zip
Description The zip file resource
Type array

Name zip_entry
Description Directory entry resource returned by m_zip_read()
Type array

Name mode
Description The file access mode
Default value rb
Type string
Values restricted to rb

Returns…

Description Whether the operation was succesful
Type boolean

Return to the function index for this class Expand: View the source code to this function

boolean zip_entry_close(array zip_entry)

Closes a directory entry previously opened for reading.

Parameters…

Name zip_entry
Description Directory entry resource returned by m_zip_read()
Type array

Returns…

Description Whether the operation was succesful
Type boolean

Return to the function index for this class Expand: View the source code to this function

string zip_entry_name(array zip_entry)

Returns the name of the directory entry specified in the given entry.

Parameters…

Name zip_entry
Description Directory entry resource returned by m_zip_read()
Type array

Returns…

Description The entry name
Type string

Return to the function index for this class Expand: View the source code to this function

integer zip_entry_filesize(array zip_entry)

Returns the filesize of the directory entry specified in the given entry.

Parameters…

Name zip_entry
Description Directory entry resource returned by m_zip_read()
Type array

Returns…

Description The file size
Type integer

Return to the function index for this class Expand: View the source code to this function

~string zip_entry_read(array zip_entry, integer zip_entry_file_size)

Returns the file data of the directory entry specified in the given entry.

Parameters…

Name zip_entry
Description Directory entry resource returned by m_zip_read()
Type array

Name zip_entry_file_size
Description The maximum returned data size
Default value 1024
Type integer

Returns…

Description The data (false: failure)
Type ~string

Return to the function index for this class Expand: View the source code to this function

void m_deldir(PATH a_dir)

Delete a directory of files.From "User Contributed Notes" at PHP: rmdir - Manual. Thanks flexer at cutephp dot com

Parameters…

Name a_dir
Description The path to the directory
Type PATH

(No return value)


Return to the function index for this class Expand: View the source code to this function

sources/zip.php

Global_functions_zip.php

Function summary

array zip_scan_folder (PATH path, PATH subpath)
?integer crc32_file (PATH filename)
mixed create_zip_file (array file_array, boolean stream, boolean get_offsets)

array zip_scan_folder(PATH path, PATH subpath)

Find file meta information for adding to a zip file

Parameters…

Name path
Description The full path to the folder to add
Type PATH

Name subpath
Description The subpath relative to the path (should be left as the default '', as this is used for the recursion to distinguish the adding base path from where it's currently looking)
Default value
Type PATH

Returns…

Description A list of maps that stores time,full_path,name, for each file
Type array

Return to the function index for this class Expand: View the source code to this function

?integer crc32_file(PATH filename)

Calculate CRC32 for a file. Based on a function in the PHP docs.

Parameters…

Name filename
Description The file
Type PATH

Returns…

Description The CRC (NULL: error)
Type ?integer

Return to the function index for this class Expand: View the source code to this function

mixed create_zip_file(array file_array, boolean stream, boolean get_offsets)

Create a zip file.

Parameters…

Name file_array
Description A list of maps (time,data/full_path,name) covering everything to zip up
Type array

Name stream
Description Whether to stream the output direct to the browser
Default value boolean-false
Type boolean

Name get_offsets
Description Whether to return the tuple
Default value boolean-false
Type boolean

Returns…

Description The data for the zip file OR a tuple: data, offsets, sizes
Type mixed

Return to the function index for this class Expand: View the source code to this function