giomba
/
opensc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

- wrote a bunch of manual pages 

git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@976 c6295689-39f2-0310-b995-f0e70906c6a9
This commit is contained in:
okir 2003-04-03 14:34:20 +00:00
parent fa2e617cd1
commit 34b5c87399
13 changed files with 499 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/sc_connect_card.3 Normal file
View File

@ -0,0 +1,30 @@
.TH sc_connect_card 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_connect_card \- connect to smart card in reader
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_connect_card(sc_reader_t *" reader ",
.BI " int " slot ", sc_card_t **" card ");
.fi
.SH DESCRIPTION
This function connects to a card in a reader, resets the card
and retrieves the ATR (Answer To Reset). Based on the ATR, it
tries to auto-detect which card driver to use.
.PP
The \fIslot\fP parameter identifies the card reader's slot.
Slots are numbered consecutively, starting at \fB0\fP.
.PP
If OpenSC was able to connect to the card, a pointer to the
\fBsc_card_t\fP object is stored in the location pointer to
by the \fIcard\fP parameter. The card handle should be
released with \fBsc_disconnect_card\fP(3) when no longer in used.
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return 0.
.SH SEE ALSO
.BR sc_establish_context (3),
.BR sc_disconnect_card (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

36
docs/sc_detect_card_presence.3 Normal file
View File

@ -0,0 +1,36 @@
.TH sc_detect_card_presence 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_detect_card_presence \- detect whether a card is present in a reader
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_detect_card_presence(sc_reader_t *" reader ",
.BI " int " slot ");
.fi
.SH DESCRIPTION
This function is used to detect the presence of a smart card in
a card reader device. The \fIslot\fP parameter identifies the
card reader's slot. Slots are numbered consecutively, starting at
\fB0\fP.
.SH RETURN VALUE
If a card is present, a positive value is returned that is a combination
of the following flags:
.TP
.B SC_SLOT_CARD_PRESENT
A card was detected.
.TP
.B SC_SLOT_CARD_CHANGED
The card was inserted and/or removed since the last call. Note that
this flag is not entirely reliable depending on the OS platform and
middleware. CTAPI doesn't support it at all, for instance, while PCSC
on Windows occasionally returns false CHANGE events.
.PP
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3).
.SH SEE ALSO
.BR sc_establish_context (3),
.BR sc_wait_for_event (3),
.BR sc_connect_card (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

26
docs/sc_disconnect_card.3 Normal file
View File

@ -0,0 +1,26 @@
.TH sc_disconnect_card 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_disconnect_card \- disconnect from smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_disconnect_card(sc_card_t *" card ",
.BI " int " action ");
.fi
.SH DESCRIPTION
This function disconnects from a card in a reader, and frees the card
structure. Any locks made by the application must be released before
calling this function.
.PP
The \fIaction\fP parameter is not used at the moment and
should be set to 0.
.PP
The card is not reset nor powered down after the operation.
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return 0.
.SH SEE ALSO
.BR sc_connect_card (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

61
docs/sc_establish_context.3 Normal file
View File

@ -0,0 +1,61 @@
.TH sc_establish_context 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_establish_context \- establish OpenSC context
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_establish_context(sc_context_t **" ctx ",
.BI " const char *" app_name ");
.fi
.SH DESCRIPTION
This function establishes an OpenSC context. This context is required
in all subsequent calls to OpenSC functions.
.PP
\fIctx\fP is a pointer to a pointer that will receive the allocated context.
.PP
\fIapp_name\fP is a string that identifies the application. This string will
be used to apply application-specific from the \fBopensc.conf\fP(5) configuration
file. If \fBNULL\fP is passed, just the settings specified in the \fBdefault\fP
section apply; otherwise, settings from the section identified by \fIapp_name\fP
will be applied as well.
.PP
The \fBsc_context\fP structure contains the following members, among
others:
.PP
.in +4
.nf
.B "typedef struct sc_context {
.B " struct sc_reader *reader[SC_MAX_READERS];
.B " int reader_count;
.B "} sc_context_t;
.fi
.in
.PP
The \fBreader_count\fP field contains the number of readers found by
OpenSC. Information on the individual card readers are stored in
\fBsc_reader\fP objects, which look like follows:
.PP
.in +4
.nf
.B "typedef struct sc_reader {
.B " char *name;
.B " int slot_count;
.B "} sc_reader_t;
.fi
.in
.PP
Here, \fBname\fP contains a printable name of the reader, and \fBslot_count\fP
shows the number of slots supported by this device.
.PP
Of course, these structs contain other members as well, but applications
usually should not use these fields.
.SH RETURN VALUE
If a context could be established, 0 is returned. Otherwise, a negative
error code is returned, as described in \fbsc_error\fP(3).
.SH SEE ALSO
.BR sc_release_context (3),
.BR sc_detect_card_presence (3),
.BR sc_connect_card (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

65
docs/sc_file.3 Normal file
View File

@ -0,0 +1,65 @@
.TH sc_file 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_file \- OpenSC file struct
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.B "typedef struct sc_file {
.B " struct sc_path path;
.B " int type, ef_structure;
.B " size_t size;
.B " int id;
.B "
.B " /* record structured files only */
.B " int record_length;
.B " int record_count;
.B "} sc_file_t;
.fi
.SH DESCRIPTION
This structure describes a file object on a smart card.
It contains the following members:
.TP
.B path
This is the full path to the file, starting at the MF.
.TP
.B type
This is the file type. If can be one of
.BR SC_FILE_TYPE_DF ,
.BR SC_FILE_TYPE_WORKING_EF ", or
.BR SC_FILE_TYPE_INTERNAL_EF .
The latter is used by some cards only, and you normally shouldn't
have to deal with these files.
.TP
.B ef_structure
For elementary files (EFs), this field describes the file's
structure. It can be one of
.IP
.nf
.BR SC_FILE_EF_TRANSPARENT
.BR SC_FILE_EF_LINEAR_FIXED
.BR SC_FILE_EF_LINEAR_FIXED_TLV
.BR SC_FILE_EF_LINEAR_VARIABLE
.BR SC_FILE_EF_LINEAR_VARIABLE_TLV
.BR SC_FILE_EF_CYCLIC
.BR SC_FILE_EF_CYCLIC_TLV
.BR SC_FILE_EF_UNKNOWN
.fi
.TP
.B size
gives the file's size in bytes.
.TP
.B id
gives the file's ID, as a 16bit number.
.TP
.BR record_count ", " record_length
For record structured files, \fBrecord_count\fP specifies the
number of records in the file. For files with fixed length
records, \fBrecord_length\fP contains the record length.
.SH SEE ALSO
.BR sc_path (3),
.BR sc_file_new (3),
.BR sc_file_free (3),
.BR sc_select_file (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

17
docs/sc_file_free.3 Normal file
View File

@ -0,0 +1,17 @@
.TH sc_file_free 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_file_free \- release an OpenSC file object
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "void sc_file_free(sc_file_t *" file ");
.fi
.SH DESCRIPTION
This function releases a file object previously allocated by
\fBsc_select_file\fP.
.SH SEE ALSO
.BR sc_file (3),
.BR sc_select_file (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

18
docs/sc_file_new.3 Normal file
View File

@ -0,0 +1,18 @@
.TH sc_file_new 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_file_new \- create an OpenSC file object
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "sc_file_t *sc_file_new(void);
.fi
.SH DESCRIPTION
This function creates an empty OpenSC file object, which
can later be passed to \fBsc_create_file\fP(3).
.SH SEE ALSO
.BR sc_file (3),
.BR sc_file_free (3),
.BR sc_create_file (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

33
docs/sc_list_files.3 Normal file
View File

@ -0,0 +1,33 @@
.TH sc_list_files 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_list_files \- list files on a smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_list_files(sc_card_t *" card ",
.BI " unsigned char *" buffer ",
.BI " size_t " buflen ");
.fi
.SH DESCRIPTION
This function lists all files in the currently selected DF,
and stores the the file IDs as big-endian 16bit words
in \fIbuffer\fP. If the supplied buffer is too small to
hold all file IDs, the listing is silently truncated.
.PP
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return the
number of bytes stored in \fIbuffer\fP.
.SH SEE ALSO
.BR sc_file (3),
.BR sc_path (3),
.BR sc_establish_context (3),
.BR sc_select_file (3),
.BR sc_read_binary (3),
.BR sc_read_record (3),
.BR sc_delete_file (3),
.BR sc_create_file (3),
.BR sc_file_free (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

46
docs/sc_lock.3 Normal file
View File

@ -0,0 +1,46 @@
.TH sc_lock 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_lock, sc_unlock \- lock or unlock smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_lock(sc_card_t *" card ");
.BI "int sc_unlock(sc_card_t *" card ");
.fi
.SH DESCRIPTION
These functions handle locking of smart cards, in order to prevent
concurrent access to the same card by different users.
.PP
Locking is important to prevent unauthorized access to the card
after presenting the PIN, for instance.
.PP
After a call to \fBsc_lock\fP, concurrent access by other application
to the same smart card reader is disallowed, provided the reader
middleware supports this (see below). A lock must later be released
by calling \fBsc_unlock\fP. When disconnecting from the card using
\fBsc_disconnect_card\fP, there must not be anymore locks on the
card.
.PP
Calls to \fBsc_lock\fP may be nested, i.e. if \fBsc_lock\fP is called
five times in a row, the lock will not be released until the fifth
call to \fBsc_unlock\fP.
.PP
Note that these functions do not offer mutual exclusion for different
threads within the same application process. Multithread locking is
the application's job (Note that the OpenSC PKCS11 module provides
MT locking facilities, as that's part of the standard).
.SH NOTES
Whether locking is effective depends a lot on the middleware
used to talk to the card reader. CTAPI based drivers for instance
perform no interprocess locking at all.
.PP
The only middleware implementation currently used by OpenSC that
does perform this type of locking is PCSC.
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return 0.
.SH SEE ALSO
.BR sc_connect_card (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

54
docs/sc_read_binary.3 Normal file
View File

@ -0,0 +1,54 @@
.TH sc_read_binary 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_read_binary, sc_write_binary, sc_update_binary \- read and write files on a smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_read_binary(sc_card_t *" card ",
.BI " unsigned int " offset ",
.BI " unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.BI "int sc_write_binary(sc_card_t *" card ",
.BI " unsigned int " offset ",
.BI " const unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.BI "int sc_update_binary(sc_card_t *" card ",
.BI " unsigned int " offset ",
.BI " const unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.fi
.SH DESCRIPTION
This functions read and write transparent elementary files (EFs)
on a smart card. The correspond to the ISO 7816 functions
READ BINARY, WRITE BINARY and UPDATE BINARY, respectively.
(The difference between write and update is that the former
means writing to an uninitialized file, while the latter
is intended to update a file region previously written to -
some card have different access conditions for these operations).
.PP
The \fIoffset\fP argument specifies the file offset in bytes.
Note that some cards may not allow writing at arbitrary offsets.
Some versions of the GPK require that read/write operations on
transparent files are aligned on a 4-byte boundary.
.PP
The \fIflags\fP argument is currently not used, and should be set
to 0.
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return the
number of bytes read or written.
.SH SEE ALSO
.BR sc_file (3),
.BR sc_path (3),
.BR sc_establish_context (3),
.BR sc_select_file (3),
.BR sc_read_record (3),
.BR sc_delete_file (3),
.BR sc_create_file (3),
.BR sc_file_free (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

56
docs/sc_read_record.3 Normal file
View File

@ -0,0 +1,56 @@
.TH sc_read_record 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_read_record, sc_write_record, sc_update_record \- read and write files on a smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_read_record(sc_card_t *" card ",
.BI " unsigned int " rec_nr ",
.BI " unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.BI "int sc_write_record(sc_card_t *" card ",
.BI " unsigned int " rec_nr ",
.BI " const unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.BI "int sc_update_record(sc_card_t *" card ",
.BI " unsigned int " rec_nr ",
.BI " const unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.BI "int sc_append_record(sc_card_t *" card ",
.BI " const unsigned char *" buffer ",
.BI " size_t " count ",
.BI " unsigned long " flags ");
.fi
.SH DESCRIPTION
This functions read and write record-structured elementary files
(EFs) on a smart card. The correspond to the ISO 7816 functions READ
RECORD, WRITE RECORD, APPEND RECORD and UPDATE RECORD, respectively.
(The difference between write and update is that the former means writing
to an uninitialized file, while the latter is intended to update a record
previously written to - some card have different access conditions for
these operations).
.PP
The \fIrec_nr\fP argument specifies the number of the record to be
written to, starting at 0.
.PP
The \fIflags\fP argument is currently not used, and should be set
to 0.
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return the
number of bytes read or written.
.SH SEE ALSO
.BR sc_file (3),
.BR sc_path (3),
.BR sc_establish_context (3),
.BR sc_select_file (3),
.BR sc_read_binary (3),
.BR sc_delete_file (3),
.BR sc_create_file (3),
.BR sc_file_free (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

19
docs/sc_release_context.3 Normal file
View File

@ -0,0 +1,19 @@
.TH sc_release_context 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_release_context \- release OpenSC context
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_release_context(struct sc_context **" ctx ");
.fi
.SH DESCRIPTION
This function releasees an OpenSC context previously obtain through
a call to \fBsc_establish_context\fP(3). No further calls to
OpenSC using this context are possible after this.
.PP
\fIctx\fP is the pointer to the context that should be released.
.SH SEE ALSO
.BR sc_establish_context (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>

38
docs/sc_select_file.3 Normal file
View File

@ -0,0 +1,38 @@
.TH sc_select_file 3 "April 2003" "OpenSC Programmer's Manual
.SH NAME
sc_select_file \- select a file on a smart card
.SH SYNOPSIS
.nf
.B #include <opensc.h>
.sp
.BI "int sc_select_file(sc_card_t *" card ",
.BI " const sc_path_t *" path ",
.BI " sc_file_t ** "result ");
.fi
.SH DESCRIPTION
This function selects the file specified by \fIpath\fP.
If \fIpath\fP specifies a file within the currently selected
DF, \fBsc_select_file\fP will \fInot\fP select the MF first,
but interpret the path relative to the current DF. It does
this in order to prevent losing any authorizations previously
established with the card (e.g. by presenting a PIN).
.PP
If \fIresult\fP is not NULL, an \fBsc_file\fP(3) object is
created, and the pointer to this object is stored in the
location pointed to by \fIresult\fP. This handle should later
be released using \fBsc_file_free\fP(3).
.SH RETURN VALUE
If an error occurred, a negative error code is returned, as described
in \fbsc_error\fP(3). Otherwise, the function will return 0.
.SH SEE ALSO
.BR sc_file (3),
.BR sc_path (3),
.BR sc_establish_context (3),
.BR sc_file_free (3),
.BR sc_read_binary (3),
.BR sc_read_record (3),
.BR sc_delete_file (3),
.BR sc_list_files (3),
.BR sc_create_file (3).
.SH AUTHOR
This manual page was written by Olaf Kirch <okir@suse.de>