.\" $Id: nsr_data.5,v 6.4 2004/06/05 22:35:46 btompkin Exp $ Copyright (c) 2004, LEGATO Software, a division of EMC"
.\" Copyright (c) 1990-1995 Legato Systems, Incorporated.
.\" All rights reserved.
.TH NSR_DATA 5 "Aug 23, 06" "StorEdge EBS 7.3.2"
.SH NAME
nsr_data \- Data formats for Sun StorEdge EBS Save and Recover
.SH DESCRIPTION
All data in the
Sun StorEdge EBS system is encoded using the
.I "eXternal Data Representation"
(XDR) standard.
When files are passed between client (see
.BR save (8)
and
.BR recover (8))
and server (see
.BR nsrd (8))
and media (see
.BR nsrmmd (8)),
they are represented as a
.IR savestream ,
which is encoded as a linked list of
.IR savefiles .
There are currently 2 different
.I savefile
formats.
A magic number at the start of each
file indicates the particular type of the following
.I savefile
thus allowing for self identifying
.I savestreams
containing more than one
.I savefile
type.
Logically each
.I savefile
consists of some header information followed by file data.
The original
.I savefile1
format uses a doubly wrapped set of client
attributes describing the file attributes
and the file data is encoded as a
.IR bucketlist .
The newer
.I savefile2
format uses an alternate singularly wrapped
client attributes with the file data encoded as
a bucket-less succession of self describing sections
each containing a type, a length, and bytes of data.
The file data section of a file is terminated
by an ending section with a type of 0 (NSR_ASDF_END).
.LP
The XDR language description of the OS independent portion of the
.I savestream
data structures is shown below.
.\".RS
.LP
.nf
\fR\s10
.ta 35n
const NSR_IDLEN = 1024;	/* length of file id */
const NSR_MAXNAMELEN = 1024;	/* max length of file system name */
const NSR_MAXCATTRSIZE = 8192;	/* max size of client specific attributes */
const NSR_MAXBUCKETDATA = 8192;	/* max size of file bucket's data (w/o slop) */
const NSR_MAXBUCKETSIZE = 9000;	/* max total size of file bucket (w/ slop) */
const NSR_MAXCLNTSIZE = 16384;	/* max size of a clntrec */
.ta 45n

typedef opaque fileid<NSR_IDLEN>;	/* file identifier */
typedef string nsrname<NSR_MAXNAMELEN>;	/* file name type */
typedef opaque clientattr<NSR_MAXCATTRSIZE>;	/* client attributes */
typedef opaque wraposaverec<NSR_MAXCLNTSIZE>;	/* wrapped osaverec */
typedef uint32_t checksum;	/* 4 bytes for checksum */
typedef u_long sfid_t;	/* savefile id (offset) */

.ta 6n 35n
struct id {
	string id_str<>;	/* id string */
	id *id_next;	/* next such structure */
};

struct asmrec {
	id *ar_info;	/* name and args to ASM */
	nsrname *ar_path;	/* not currently used */
	asmrec *ar_next;	/* next such structure */
};

const NSR_MAGIC1 = 0x09265900;	/* older format using buckets & ssaverec's */

struct osaverec {
	nsrname sr_filename;	/* name of this file */
	fileid sr_fid;	/* client specific file id */
	asmrec *sr_ar;	/* ASM list for this file */
	u_long sr_catype;	/* client specific attribute type */
	clientattr sr_cattr;	/* client specific file attributes */
};

struct ssaverec {
	sfid_t sr_id;	/* savefile id in the savestream */
	u_long sr_size;	/* size of encoded savefile */
	uint32_t sr_savetime;	/* savetime of this saveset */
	wraposaverec sr_wcr;	/* a wrapped osaverec */
};

/*
 * File data for older style savestream is logically
 * expressed as a linked list of file buckets.
 */
struct bucketlist {
	bucket bl_bucket;
	bucketlist *bl_next;
};

/*
 * XDR description of the original savefile1 format.
 */
struct savefile1 {
	u_long sf_magic;	/* magic number (must be NSR_MAGIC1) */
	u_long sf_chksumtype;	/* file checksum type */
	ssaverec sf_saverec;	/* wrapped file attributes */
	bucketlist *sf_data;	/* file data in buckets */
	checksum sf_checksum;	/* checksum value */
};

/*
 * New savestream defines and structures.
 */
const NSR_MAGIC2 = 0x03175800;	/* newer bucketless format */

const NSRAPP_BACKUP = 1;	/* backup application name space */
const NSRAPP_HSM = 2;	/* HSM application name space */
const NSRAPP_ARCHIVE = 3;	/* Archive application name space */

struct saverec {
	sfid_t sr_id;	/* savefile id in the savestream */
	u_long sr_size;	/* size of encoded savefile */
	uint32_t sr_savetime;	/* savetime of this saveset */
	uint32_t sr_appid;	/* application id */
	nsrname sr_filename;	/* name of encoded file */
	fileid sr_fid;	/* client specific file id */
	asmrec *sr_ar;	/* ASM list for this file */
	u_long sr_catype;	/* client specific attribute type */
	clientattr sr_cattr;	/* client specific file attributes */
};

/*
 * Defines for self describing data sections.
 * The NSR_ASDF_END type defines the end of the file data.
 * The NSR_ASDF_FILE_DATA_TYPE type has the file data preceded by an
 * uint32_t that is the relative offset from the last block into the file.
 */
.ta 45n
const NSR_ASDF_END = 0x0;	/* end of ASDF data */
const NSR_ASDF_FILE_DATA_TYPE = 0x100;	/* normal file data */
.ta 6n 35n

/*
 * Describes a section of Sun StorEdge EBS "file data" when
 * using ASM Structured Data Format (ASDF) sections.
 */
struct asdf_hdr {
	uint32_t typevers;	/* type of file data */
	uint32_t length;	/* section length */
};

/*
 * Pseudo XDR description of the newer savefile2 format.
 * The new savefile2 format uses the unwrapped saverec structure
 * and a "bucketless" file data format that is based on ASDF.
 * The data portion ends with a 0 sized section of type NSR_ASDF_END.
 */
struct savefile2 {
	u_long sf_magic;	/* magic number (must be SF_MAGIC2) */
	u_long sf_chksumtype;	/* file checksum type */
	saverec sf_saverec;	/* new saverec structure */
	<asdf_hdr & data>	/* ASDF section sans buckets */
	    \.\.\.
	<asdf_hdr & data>	/* ASDF section sans buckets */
	<asdf_hdr.typevers = 0>	/* final ASDF section type = NSR_ASDF_END */
	<asdf_hdr.length = 0>	/* final ASDF section len = 0 */
	checksum sf_checksum;	/* checksum value */
};

\fP\s0
.fi
.RE
.LP
.SH SEE ALSO
.PD 0
.na
.BR mm_data (5),
.BR nsr (8),
.BR nsrmmd (8),
.BR nsrd (8),
.BR recover (8),
.BR save (8),
.BR xdr (3n)
.TP 20
RFC 1014 XDR Protocol Spec
.PD
.ad