Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_get_index_by_NID.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "X509_NAME_get_index_by_NID 3"
e3261593 127.TH X509_NAME_get_index_by_NID 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
134X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
135X509_NAME lookup and enumeration functions
136.SH "SYNOPSIS"
8b0cefbb 137.IX Header "SYNOPSIS"
01185282
PA
138.Vb 1
139\& #include <openssl/x509.h>
140\&
141\& int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
142\& int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
143\&
144\& int X509_NAME_entry_count(X509_NAME *name);
145\& X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
146\&
147\& int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
148\& int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
149.Ve
984263bc 150.SH "DESCRIPTION"
8b0cefbb 151.IX Header "DESCRIPTION"
984263bc 152These functions allow an \fBX509_NAME\fR structure to be examined. The
8b0cefbb
JR
153\&\fBX509_NAME\fR structure is the same as the \fBName\fR type defined in
154\&\s-1RFC2459\s0 (and elsewhere) and used for example in certificate subject
984263bc
MD
155and issuer names.
156.PP
8b0cefbb 157\&\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR retrieve
984263bc
MD
158the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
159should initially be set to \-1. If there are no more entries \-1 is returned.
160.PP
8b0cefbb 161\&\fIX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR.
984263bc 162.PP
8b0cefbb 163\&\fIX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR
984263bc 164corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
8b0cefbb 1650 to (X509_NAME_entry_count(name) \- 1). The value returned is an
984263bc
MD
166internal pointer which must not be freed.
167.PP
8b0cefbb 168\&\fIX509_NAME_get_text_by_NID()\fR, \fIX509_NAME_get_text_by_OBJ()\fR retrieve
984263bc 169the \*(L"text\*(R" from the first entry in \fBname\fR which matches \fBnid\fR or
8b0cefbb 170\&\fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes
984263bc
MD
171will be written and the text written to \fBbuf\fR will be null
172terminated. The length of the output string written is returned
8b0cefbb 173excluding the terminating null. If \fBbuf\fR is <\s-1NULL\s0> then the amount
e257b235 174of space needed in \fBbuf\fR (excluding the final null) is returned.
984263bc 175.SH "NOTES"
8b0cefbb
JR
176.IX Header "NOTES"
177\&\fIX509_NAME_get_text_by_NID()\fR and \fIX509_NAME_get_text_by_OBJ()\fR are
984263bc
MD
178legacy functions which have various limitations which make them
179of minimal use in practice. They can only find the first matching
180entry and will copy the contents of the field verbatim: this can
181be highly confusing if the target is a muticharacter string type
182like a BMPString or a UTF8String.
183.PP
184For a more general solution \fIX509_NAME_get_index_by_NID()\fR or
8b0cefbb
JR
185\&\fIX509_NAME_get_index_by_OBJ()\fR should be used followed by
186\&\fIX509_NAME_get_entry()\fR on any matching indices and then the
984263bc
MD
187various \fBX509_NAME_ENTRY\fR utility functions on the result.
188.SH "EXAMPLES"
8b0cefbb 189.IX Header "EXAMPLES"
984263bc
MD
190Process all entries:
191.PP
192.Vb 2
193\& int i;
194\& X509_NAME_ENTRY *e;
e257b235 195\&
984263bc
MD
196\& for (i = 0; i < X509_NAME_entry_count(nm); i++)
197\& {
198\& e = X509_NAME_get_entry(nm, i);
199\& /* Do something with e */
200\& }
201.Ve
8b0cefbb 202.PP
984263bc
MD
203Process all commonName entries:
204.PP
205.Vb 2
206\& int loc;
207\& X509_NAME_ENTRY *e;
e257b235
PA
208\&
209\& loc = \-1;
984263bc
MD
210\& for (;;)
211\& {
212\& lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
e257b235 213\& if (lastpos == \-1)
984263bc
MD
214\& break;
215\& e = X509_NAME_get_entry(nm, lastpos);
216\& /* Do something with e */
217\& }
218.Ve
219.SH "RETURN VALUES"
8b0cefbb
JR
220.IX Header "RETURN VALUES"
221\&\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR
984263bc
MD
222return the index of the next matching entry or \-1 if not found.
223.PP
8b0cefbb 224\&\fIX509_NAME_entry_count()\fR returns the total number of entries.
984263bc 225.PP
8b0cefbb
JR
226\&\fIX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the
227requested entry or \fB\s-1NULL\s0\fR if the index is invalid.
984263bc 228.SH "SEE ALSO"
74dab6c2 229.IX Header "SEE ALSO"
8b0cefbb
JR
230\&\fIERR_get_error\fR\|(3), \fId2i_X509_NAME\fR\|(3)
231.SH "HISTORY"
984263bc 232.IX Header "HISTORY"
8b0cefbb 233\&\s-1TBA\s0