docs/buxton_key_create.3

   1 '\" t
   2 .TH "BUXTON_KEY_CREATE" "3" "buxton 1" "buxton_key_create"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 buxton_key_create, buxton_key_free, buxton_key_get_layer,
  24 buxton_key_get_type, buxton_key_get_group, buxton_key_get_name \-
  25 Manage groups and key\-names for buxton clients
  26
  27 .SH "SYNOPSIS"
  28 .nf
  29 \fB
  30 #include <buxton.h>
  31 \fR
  32 .sp
  33 \fB
  34 BuxtonKey buxton_key_create(char *\fIgroup\fB,
  35 .br
  36                             char *\fIname\fB,
  37 .br
  38                             char *\fIlayer\fB,
  39 .br
  40                             BuxtonDataType \fItype\fB)
  41 .sp
  42 .br
  43 char *buxton_key_get_layer(BuxtonKey \fIkey\fB)
  44 .sp
  45 .br
  46 char *buxton_key_get_group(BuxtonKey \fIkey\fB)
  47 .sp
  48 .br
  49 char *buxton_key_get_name(BuxtonKey \fIkey\fB)
  50 .sp
  51 .br
  52 BuxtonDataType buxton_key_get_type(BuxtonKey \fIkey\fB)
  53 .sp
  54 .br
  55 void buxton_key_free(BuxtonKey \fIkey\fB)
  56 \fR
  57 .fi
  58
  59 .SH "DESCRIPTION"
  60 .PP
  61 These functions are used by buxton clients to manage groups and
  62 key\-names, both represented by a BuxtonKey\&. BuxtonKeys are
  63 required for all configuration management operations within buxton.
  64
  65 A BuxtonKey is created with \fBbuxton_key_create\fR(3). Its arguments
  66 serve to initialize the BuxtonKey contents, which include the name of
  67 the \fIlayer\fR, name of the \fIgroup\fR, name of the key \fIname\fR,
  68 and the \fItype\fR of the key name\&. Groups must be initialized by
  69 passing a NULL value for \fIname\fR; similarly, key\-names must be
  70 initialized by passing non\-NULL arguments for both \fIgroup\fR and
  71 \fIname\fR\&. For groups, the \fItype\fR is ignored\&. The function
  72 returns an initialized BuxtonKey\&.
  73
  74 Note that upon creation, a BuxtonKey is either a group or key\-name,
  75 but not both\&. In other words, if a client needs to a create a group
  76 and key\-name within that group, two BuxtonKeys need to be created\&.
  77
  78 After creating a BuxtonKey, its layer, group, key name, or key name
  79 type fields can be requested by calling
  80 \fBbuxton_key_get_layer\fR(3), \fBbuxton_key_get_group\fR(3),
  81 \fBbuxton_key_get_name\fR(3), or \fBbuxton_key_get_type\fR(3),
  82 respectively\&. Each of these functions take a single argument, the
  83 BuxtonKey that is being queried, and return the value requested\&.
  84 Note that calling \fBbuxton_key_get_type\fR(3) for a group will
  85 return STRING, since buxton treats groups as strings internally\&.
  86 Calling \fBbuxton_key_get_name\fR(3) for a group will return NULL,
  87 since the name field is not used for groups\&.
  88
  89 All BuxtonKey's are freed automatically on buxton_close, but can
  90 be freed manually if desired by calling \fBbuxton_key_free\fR(3)\&.
  91 This function takes a single argument, the BuxtonKey to be freed\&.
  92
  93 .SH "COPYRIGHT"
  94 .PP
  95 Copyright 2014 Intel Corporation\&. License: Creative Commons
  96 Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2\&.
  97
  98 .SH "SEE ALSO"
  99 .PP
 100 \fBbuxton\fR(7),
 101 \fBbuxtond\fR(8),
 102 \fBbuxton\-api\fR(7)
 103
 104 .SH "NOTES"
 105 .IP " 1." 4
 106 Creative Commons Attribution\-ShareAlike 3.0 Unported
 107 .RS 4
 108 \%http://creativecommons.org/licenses/by-sa/3.0/
 109 .RE