Changeset 38

Show
Ignore:
Timestamp:
06/04/08 16:35:15 (6 months ago)
Author:
jtang
Message:

Revised all man pages to match current API.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/libsipc/man/man3/sipc_close.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_CLOSE" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    …… 
    1313.hy 
    1414.SH "DESCRIPTION" 
    15 \fBsipc_close\fR() frees memory associated with a secure IPC handle  
     15\fBsipc_close\fR() frees memory associated with a secure IPC handle 
    1616that was obtained via \fBsipc_open\fR() and detaches from the 
    1717associated IPC resource. 
     18Nothing occurs if 
     19.IR sipc 
     20is NULL. 
     21Undefined behavior occurs if the same handle is closed multiple times. 
     22.P 
    1823Note that \fBsipc_close\fR() does not destroy the underlying IPC resource; 
    1924that is done by \fBsipc_unlink\fR(). 

  • trunk/libsipc/man/man3/sipc_error.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_ERROR" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    44.SH NAME 
    5 sipc_error \- Print messages for errors that occur during secure IPC.  
     5sipc_error \- Print messages for errors that occur during secure IPC 
    66.SH "SYNOPSIS" 
    77.ad l 
    …… 
    99#include <sipc/sipc.h> 
    1010.HP 20 
    11 void\ \fBsipc_error\fR\ (sipc_t\ \fI*sipc\fR, char\ \fI*format\fR, ...); 
     11void\ \fBsipc_error\fR(sipc_t\ \fI*sipc\fR, char\ \fI*format\fR, ...); 
    1212.ad 
    1313.hy 
    1414.SH "DESCRIPTION" 
    15 \fBsipc_error\fR is used for reporting errors that occur during secure IPC.  
    16 This function recognizes \fBprintf(3)\fR style format strings.  
     15\fBsipc_error\fR is used for reporting errors that occur during secure IPC. 
     16This function recognizes \fBprintf(3)\fR style format strings. 
    1717.SH "RETURN VALUE" 
    1818This function has no return value. 
    1919.SH "SEE ALSO" 
    20 \fBsipc_send_data(3)\fR, \fBsipc_connect(3)\fR, \fBsipc_disconnect(3)\fR. 
     20\fBsipc_open(3)\fR, \fBsipc_close(3)\fR 
    2121.SH AUTHOR 
    2222David Windsor <dwindsor@tresys.com> 

  • trunk/libsipc/man/man3/sipc_get_data_ptr.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_GET_DATA_PTR" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    44.SH NAME 
    5 sipc_get_data_ptr \- Get a pointer to a secure IPC handle's data. 
     5sipc_get_data_ptr \- Get a pointer to a secure IPC handle's sending data buffer 
    66.SH "SYNOPSIS" 
    77.ad l 
    …… 
    99#include <sipc/sipc.h> 
    1010.HP 20 
    11 char\ *\fBsipc_get_data_ptr\fR\ (sipc_t\ \fI*sipc\fR); 
     11char\ *\fBsipc_get_data_ptr\fR(sipc_t\ \fI*sipc\fR); 
    1212.ad 
    1313.hy 
    1414.SH "DESCRIPTION" 
    15 \fBsipc_get_data_ptr\fR is used to access the data associated with an 
     15\fBsipc_get_data_ptr\fR() is used to access the data associated with an 
    1616IPC handle. 
     17The contents of the pointed to memory will be sent upon a call to 
     18\fBsipc_send_data\fR(). 
     19.P 
     20Do not \fBfree\fR() or otherwise deallocate the returned pointer. 
    1721.SH "RETURN VALUE" 
    18 This function returns a pointer to the handle's data member on success,  
     22This function returns a pointer to the handle's data member on success, 
    1923NULL on error. 
    2024.SH "EXAMPLES" 
    …… 
    2933.fi 
    3034.SH "SEE ALSO" 
    31 \fBsipc_init(3)\fR, \fBsipc_disconnect(3)\fR, \fBsipc_send_data(3)\fR, \fBsipc_recv_data(3)\fR, \fBsipc_error(3)\fR 
     35\fBsipc_send_data(3)\fR, \fBsipc_recv_data(3)\fR 
    3236.SH AUTHOR 
    3337David Windsor <dwindsor@tresys.com> 

  • trunk/libsipc/man/man3/sipc_open.3

    r21 r38  
    3535.TP 
    3636.I ipc_type 
    37 The type of IPC to be used for communications, e.g. SIPC_SYSV_MQUEUES 
     37The type of IPC to be used for communications, one of SIPC_SYSV_MQUEUES 
    3838or SIPC_SYSV_SHM. 
    3939.TP 

  • trunk/libsipc/man/man3/sipc_recv_data.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_RECV_DATA" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    44.SH NAME 
    5 sipc_recv_data \- Receive data from a secure IPC channel. 
     5sipc_recv_data \- Receive data from a secure IPC channel 
    66.SH "SYNOPSIS" 
    77.ad l 
    …… 
    99#include <sipc/sipc.h> 
    1010.HP 20 
    11 int\ \fBsipc_recv_data\fR\ (sipc_t\ \fI*sipc\fR, char\ \fI**data\fR, int\ \fI*len\fR); 
     11int\ \fBsipc_recv_data\fR(sipc_t\ \fI*sipc\fR, char\ \fI**data\fR, int\ \fI*len\fR); 
    1212.ad 
    1313.hy 
    1414.SH "DESCRIPTION" 
    15 \fBsipc_recv_data\fR receives data from a secure IPC channel. 
     15\fBsipc_recv_data\fR() receives data from a secure IPC channel. 
    1616.PP 
    1717The function parameters are as follows: 
    1818.TP 
    1919.I sipc 
    20 An IPC handle  
     20An IPC handle 
    2121.TP 
    2222.I data 
    23 Pointer to a buffer which will hold the data received from the channel  
     23Pointer to a buffer which will hold the data received from the channel 
    2424.TP 
    2525.I len 
    2626This will hold the total number of bytes received 
    2727.PP 
    28 \fBsipc_recv_data\fR allocates the buffer used to store received data. It is  
    29 the responsibility of the caller to free this data. 
     28If the IPC channel is a message queue, \fBsipc_recv_data\fR() 
     29allocates the buffer used to store received data; it is the 
     30responsibility of the caller to \fBfree()\fR this data afterwards. 
     31Otherwise, the shared memory reader must call \fBsipc_shm_recv_done\fR 
     32to unblock the sender, and no freeing should occur. 
    3033.SH "RETURN VALUE" 
    3134This function returns 0 on success, \-1 on error. 
     35Upon error, 
     36.I *data 
     37will be set to NULL and 
     38.I msg_len 
     39will be set to zero. 
    3240.SH "EXAMPLES" 
    3341.nf 
    3442/* Sample code */ 
    3543 
    36 char *data = sipc_get_data_ptr(ipc); 
     44char *data; 
     45int len; 
    3746sipc_recv_data(ipc, &data, &len); 
    38 printf("Received %s", data);   /* Do stuff with shared memory  */ 
    39 sipc_shm_recv_done(ipc);       /* When done with the data in shared memory,  
    40                                   unblock sender; this is only needed when  
    41                                   using shared memory */ 
     47printf("Received %s", data);   /* Do stuff with shared memory */ 
     48sipc_shm_recv_done(ipc);       /* Unblock sender when done; this is only 
     49                                  needed when using shared memory */ 
    4250.fi 
    4351.SH "SEE ALSO" 
    44 \fBsipc_send_data(3)\fR, \fBsipc_connect(3)\fR, \fBsipc_disconnect(3)\fR, 
    45 \fBsipc_error(3)\fR 
     52\fBsipc_send_data(3)\fR, \fBsipc_shm_recv_done(3)\fR 
    4653.SH AUTHOR 
    4754David Windsor <dwindsor@tresys.com> 

  • trunk/libsipc/man/man3/sipc_send_data.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_SEND_DATA" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    44.SH NAME 
    5 sipc_send_data \- Send data to a secure IPC channel. 
     5sipc_send_data \- Send data to a secure IPC channel 
    66.SH "SYNOPSIS" 
    77.ad l 
    …… 
    99#include <sipc/sipc.h> 
    1010.HP 20 
    11 int\ \fBsipc_send_data\fR\ (sipc_t\ \fI*sipc\fR, int\ \fImsg_len\fR); 
     11int\ \fBsipc_send_data\fR(sipc_t\ \fI*sipc\fR, int\ \fImsg_len\fR); 
    1212.ad 
    1313.hy 
    …… 
    1717the underlying IPC mechanism used, fragmentation of the data may occur 
    1818during transmission. Reassembly of fragmented data occurs transparently 
    19 at the receiver's end, with a call to \fBsipc_recv_data\fR. In the case of 
    20 shared memory, the caller must ensure that the size of the data contained 
    21 in the handle does not exceed the system shared memory segment size limit, 
    22 in which case the data will be truncated prior to transmission. 
     19at the receiver's end, with a call to \fBsipc_recv_data\fR(). 
     20.PP 
     21In the case of shared memory, the caller must ensure that the size of 
     22the data contained in the handle does not exceed the system shared 
     23memory segment size limit, in which case the data will be truncated 
     24prior to transmission. Furthermore, this function will block until the 
     25message is consumed by the reader (via \fBsipc_recv_data\fR() and 
     26\fBsipc_shm_recv_done\fR()). For channels created as message queues, no 
     27such blocking occurs. 
    2328.SH "RETURN VALUE" 
    2429This function returns 0 on success, \-1 on error. 
    …… 
    2833 
    2934char msg[] = "Hello, world."; 
    30 data = sipc_get_data_ptr(ipc);      /* Get data pointer from handle */ 
     35char *data = sipc_get_data_ptr(ipc); /* Get data pointer from handle */ 
    3136strncpy(data, msg, size);            /* Copy mesasge into the handle */ 
    3237if (sipc_send_data(ipc, size) < 0)   /* Send the message */ 
    …… 
    3439.fi 
    3540.SH "SEE ALSO" 
    36 \fBsipc_recv_data(3)\fR, \fBsipc_get_data_ptr(3)\fR, \fBsipc_connect(3)\fR, 
    37 \fBsipc_disconnect(3)\fR, \fBsipc_error(3)\fR 
     41\fBsipc_get_data_ptr(3)\fR, \fBsipc_recv_data(3)\fR 
    3842.SH AUTHOR 
    3943David Windsor <dwindsor@tresys.com> 

  • trunk/libsipc/man/man3/sipc_shm_recv_done.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_SHM_RECV_DONE" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    …… 
    99#include <sipc/sipc.h> 
    1010.HP 20 
    11 int\ \fBsipc_shm_recv_done\fR\ (sipc_t\ \fI*sipc\fR); 
     11int\ \fBsipc_shm_recv_done\fR(sipc_t\ \fI*sipc\fR); 
    1212.ad 
    1313.hy 
    1414.SH "DESCRIPTION" 
    15 \fBsipc_shm_recv_done\fR is called by an application receiving messages using  
    16 shared memory during secure IPC. \fBsipc_shm_recv_done\fR unblocks the sending  
    17 process, allowing it to send more data. This function only needs to be called  
    18 when using shared memory as a backend for secure IPC.  
     15\fBsipc_shm_recv_done\fR() is called by an application receiving 
     16messages using shared memory during secure IPC. 
     17\fBsipc_shm_recv_done\fR() unblocks the sending process, allowing it 
     18to resume processing. 
     19This function needs to be called when using shared memory as a backend 
     20for secure IPC. 
    1921.SH "RETURN VALUE" 
    2022This function returns 0 on success, \-1 on error. 
    …… 
    2325/* Sample code */ 
    2426 
    25 char *data = sipc_get_data_ptr(ipc); 
     27char *data; 
     28int len; 
    2629sipc_recv_data(ipc, &data, &len); 
    2730printf("Received %s", data);   /* Do stuff with shared memory */ 
    28 sipc_shm_recv_done(ipc);       /* When done with the data in shared memory,  
    29                                   unblock sender; this is only needed when  
    30                                   using shared memory */ 
     31sipc_shm_recv_done(ipc);       /* Unblock sender when done; this is only 
     32                                  needed when using shared memory */ 
    3133.fi 
    3234.SH "SEE ALSO" 
    33 \fBsipc_send_data(3)\fR, \fBsipc_recv_data(3)\fR, \fBsipc_error(3)\fR 
     35\fBsipc_send_data(3)\fR, \fBsipc_recv_data(3)\fR 
    3436.SH AUTHOR 
    3537David Windsor <dwindsor@tresys.com> 

  • trunk/libsipc/man/man3/sipc_unlink.3

    r21 r38  
    1 .\" Copyright (C) 2006, 2007 Tresys Technology, LLC 
     1.\" Copyright (C) 2006 - 2008 Tresys Technology, LLC 
    22.\" This file is distributed according to the GNU Lesser General Public License 
    33.TH "SIPC_UNLINK" 3 "2006-08-10" "Linux 2.6" "Linux Programmer's Manual" 
    44.SH NAME 
    5 sipc_unlink \- Free IPC resources associated with a secure IPC handle 
     5sipc_unlink \- Destroy an IPC resource from the system 
    66.SH "SYNOPSIS" 
    77.ad l 
    …… 
    1818processes actually communicating via secure IPC. 
    1919Note that even after a call to \fBsipc_unlink\fR(), the IPC resource will 
    20 continue to exist until all active connections (i.e. sender and receiver) 
     20continue to exist until all active connections (i.e., senders and receivers) 
    2121have called \fBsipc_close\fR(). 
    2222For this reason, all processes using the IPC resource should call 
    …… 
    2929.TP 
    3030.I ipc_type 
    31 One of SIPC_SYSV_MQUEUES or SIPC_SYSV_SHM for message queues  
     31One of SIPC_SYSV_MQUEUES or SIPC_SYSV_SHM for message queues 
    3232or shared memory, respectively. 
    3333.SH "RETURN VALUE" 
    3434This function has no return value. 
    3535.SH "SEE ALSO" 
    36 \fBsipc_open(3)\fR, \fBsipc_close\fR 
     36\fBsipc_open(3)\fR, \fBsipc_close(3)\fR 
    3737.SH AUTHOR 
    3838David Windsor <dwindsor@tresys.com>