.TH "owner.c" 3elektra "Mon Jan 4 2021" "Version 0.9.3" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
owner.c \- Obsolete owner methods\&.  

.SH SYNOPSIS
.br
.PP
\fC#include <kdb\&.h>\fP
.br
\fC#include <kdbconfig\&.h>\fP
.br
\fC#include <kdbmeta\&.h>\fP
.br
\fC#include <kdbprivate\&.h>\fP
.br

.SS "Functions"

.in +1c
.ti -1c
.RI "const char * \fBkeyOwner\fP (const Key *key)"
.br
.RI "Return a pointer to the real internal \fCkey\fP owner\&. "
.ti -1c
.RI "ssize_t \fBkeyGetOwnerSize\fP (const Key *key)"
.br
.RI "Return the size of the owner of the Key with concluding 0\&. "
.ti -1c
.RI "ssize_t \fBkeyGetOwner\fP (const Key *key, char *returnedOwner, size_t maxSize)"
.br
.RI "Return the owner of the key\&. "
.ti -1c
.RI "ssize_t \fBkeySetOwner\fP (Key *key, const char *newOwner)"
.br
.RI "Set the owner of a key\&. "
.in -1c
.SH "Detailed Description"
.PP 
Obsolete owner methods\&. 


.PP
\fBCopyright\fP
.RS 4
BSD License (see LICENSE\&.md or https://www.libelektra.org) 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "ssize_t keyGetOwner (const Key * key, char * returnedOwner, size_t maxSize)"

.PP
Return the owner of the key\&. 
.IP "\(bu" 2
Given \fCuser:someuser:/\fP\&.\&.\&.\&.\&. return \fCsomeuser\fP 
.IP "\(bu" 2
Given \fCuser:some\&.user:/\fP\&.\&.\&.\&. return \fCsome\&.user\fP 
.IP "\(bu" 2
Given \fCuser:/\fP\&.\&.\&.\&. return the current user
.PP
.PP
Only \fCuser:/\fP\&.\&.\&. keys have an owner\&. For \fCsystem:/\fP\&.\&.\&. keys (that doesn't have a key owner) an empty string ('') is returned\&.
.PP
Although usually the same, the owner of a key is not related to its UID\&. Owner are related to WHERE the key is stored on disk, while UIDs are related to mode controls of a key\&.
.PP
\fBParameters\fP
.RS 4
\fIkey\fP the object to work with 
.br
\fIreturnedOwner\fP a pre-allocated space to store the owner 
.br
\fImaxSize\fP maximum number of bytes that fit returned 
.RE
.PP
\fBReturns\fP
.RS 4
number of bytes written to buffer 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI1\fP if there is no owner 
.br
\fI-1\fP on NULL pointers 
.br
\fI-1\fP when maxSize is 0, larger than SSIZE_MAX or too small for ownername 
.RE
.PP
\fBSee also\fP
.RS 4
\fBkeySetName()\fP, \fBkeySetOwner()\fP, \fBkeyOwner()\fP 
.RE
.PP

.SS "ssize_t keyGetOwnerSize (const Key * key)"

.PP
Return the size of the owner of the Key with concluding 0\&. The returned number can be used to allocate a string\&. 1 will returned on an empty owner to store the concluding 0 on using \fBkeyGetOwner()\fP\&.
.PP
.PP
.nf
char * buffer;
buffer = elektraMalloc (keyGetOwnerSize (key));
// use buffer and keyGetOwnerSize (key) for maxSize
.fi
.PP
.PP
\fBNote\fP
.RS 4
that -1 might be returned on null pointer, so when you directly allocate afterwards its best to check if you will pass a null pointer before\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns\fP
.RS 4
number of bytes 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI1\fP if there is no owner 
.br
\fI-1\fP on NULL pointer 
.RE
.PP
\fBSee also\fP
.RS 4
\fBkeyGetOwner()\fP 
.RE
.PP

.SS "const char* keyOwner (const Key * key)"

.PP
Return a pointer to the real internal \fCkey\fP owner\&. This is a much more efficient version of \fBkeyGetOwner()\fP and you should use it if you are responsible enough to not mess up things\&. You are not allowed to modify the returned string in any way\&. If you need a copy of the string, consider to use \fBkeyGetOwner()\fP instead\&.
.PP
\fBkeyOwner()\fP returns '' when there is no keyOwner\&. The reason is 
.PP
.nf
key=keyNew(0);
keySetOwner(key,"");
keyOwner(key); // you would expect "" here
keySetOwner(key,"system");
keyOwner(key); // you would expect "" here

.fi
.PP
.PP
\fBNote\fP
.RS 4
Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by \fBkeyOwner()\fP method to set a new value\&. Use \fBkeySetOwner()\fP instead\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns\fP
.RS 4
a pointer to internal owner 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI''\fP when there is no (an empty) owner 
.br
\fI0\fP iff key is a NULL pointer 
.RE
.PP
\fBSee also\fP
.RS 4
\fBkeyGetOwnerSize()\fP for the size of the string with concluding 0 
.PP
\fBkeyGetOwner()\fP, \fBkeySetOwner()\fP 
.PP
\fBkeyName()\fP for name without owner 
.RE
.PP

.SS "ssize_t keySetOwner (Key * key, const char * newOwner)"

.PP
Set the owner of a key\&. an owner is a name of a system user related to a UID\&. The owner decides on which location on the disc the key goes\&.
.PP
A private copy is stored, so the passed parameter can be freed after the call\&.
.PP
\fBParameters\fP
.RS 4
\fIkey\fP the key object to work with 
.br
\fInewOwner\fP the string which describes the owner of the key 
.RE
.PP
\fBReturns\fP
.RS 4
the number of bytes actually saved including final NULL 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI1\fP when owner is freed (by setting 0 or '') 
.br
\fI-1\fP on null pointer or memory problems 
.RE
.PP
\fBSee also\fP
.RS 4
\fBkeySetName()\fP, \fBkeyGetOwner()\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Elektra from the source code\&.