.\" pragma ident "@(#)KcsSaveProfile.3	1.3  04/21/95"
.TH KcsSaveProfile 3 "21 April 1995" "" "KCMS Library"
.SH NAME
KcsSaveProfile \- Save a loaded profile to a given destination
.SH SYNOPSIS
.ft B
.nf
#include <kcms/kcs.h>
#include <kcms/kcstypes.h>
.sp
KcsStatusId KcsSaveProfile(
		KcsProfileId	profile, 
		KcsProfileDesc	*desc)
.fi
.ft R
.SH MT-LEVEL
MT-Unsafe
.SH DESCRIPTION
Use 
.B KcsSaveProfile()
to save a loaded profile and any 
changes to its attributes or profile data to the mechanism 
described by desc.
.PP
If supported by the mechanism, a profile's state can be saved at 
an offset. For example, if the mechanism indicates a file, the 
following two situations are applicable:
.sp
.in +3
Create a file containing only one profile. In this case most 
typically the offset would be 0.
.sp
Create a file containing one profile plus some application data 
(like a TIFF file). You must ensure that the profile fits into the 
file format and does not overwrite data nor is itself 
overwritten. You can determine the length of data to store in 
the file by calling 
.B KcsGetAttribute(3) 
and supplying the 
.B icHeader
attribute. The value of
.B size
in
.B icHeader
is the size of the profile.
.in -3
.PP
.B KcsSaveProfile()
writes information, but does not free the 
profile. Even after saving the profile, the application can continue 
to use it. In fact, the application must call KcsFreeProfile(3) to 
free all resources associated with the profile.
.SH ARGUMENTS
.TP
.SB profile
The identifier of the loaded profile. Typically, your application 
obtains this value when it calls KcsLoadProfile(3) or 
KcsConnectProfiles(3).
.TP
.SB desc
The location of the profile's storage mechanism, needed to obtain 
the data required to generate the profile's resources. It is 
specified as a union of independent mechanisms. This argument 
has a field that identifies which mechanism to use. If this field is 
NULL, the profile is saved through the same mechanism from 
which it was loaded. 
.SH RETURN VALUES
Upon successful completion KCS_SUCCESS is returned. Otherwise
one of the following errors will be returned.
.SH ERRORS
KCS_PROF_ID_BAD
KCS_IO_WRITE_ERR
KCS_IO_READ_ERR
KCS_IO_SEEK_ERR
KCS_SOLARIS_FILE_NOT_OPENED
KCS_SOLARIS_FILE_RO
KCS_SOLARIS_FILE_LOCKED
KCS_SOLARIS_FILE_NAME_NULL
KCS_X11_DATA_NULL
KCS_X11_PROFILE_NOT_LOADED
KCS_X11_PROFILE_RO
.SH SEE ALSO
.BR KcsConnectProfiles (3)
.BR KcsCreateProfile (3)
.BR KcsGetAttribute (3)
.BR KcsLoadProfile (3)
.BR KcsUpdateProfile (3)
.BR KcsSetAttribute (3)
.br
.BR "KCMS Application Developers Guide"
.SH EXAMPLE
.nf
KcsProfileDesc		desc;
KcsProfileId		profileid;
KcsStatusId		status;
KcsErrDesc		errDesc;

/*see example kcs_update.c for a full example code */
desc.type = KcsSolarisProfile;
desc.desc.Solarisfile.fileName = argv[1];
desc.desc.Solarisfile.hostName = NULL;
desc.desc.Solarisfile.mode = 0;
desc.desc.Solarisfile.oflag = O_RDWR

status = KcsSaveProfile(profileid, &desc);
if(status != KCS_SUCCESS) {
	status = KcsGetLastError(&errDesc);
	fprintf(stderr,"KcsSaveProfile failed error = %s\\\n", errDesc.desc);
	exit (0);
}
KcsFreeProfile(profileid);
.fi
.PP
If saving to a new profile, use the following assignments.
.sp
.nf
desc.desc.Solarisfile.oflag = O_RDWR | O_CREAT | O_TRUNC;
desc.desc.Solarisfile.mode = 0666;
.fi