send_file()

The send_file() function sends the file data over a connected socket.

Syntax

#include <types.h>
#include <sys\socket.h>
ssize_t send_file(socket_ptr, sf_struct, flags)
int * socket_ptr;
struct sf_parms * sf_struct;
int flags;

Parameters

socket_ptr

Pointer to the socket descriptor of a connected socket.

Pointer to a structure that contains variables needed by send_file().

Allows the sender to control the transmission of the message. Set this parameter by specifying one or more of the following flags. If you specify more than one flag, use the logical OR operator (|) to separate them. Setting this parameter is supported only for sockets in the Internet domain.

SF_CLOSE

Close the connection after data has been successfully sent or queued for retransmission.
SF_REUSE
Prepare the socket for reuse after the data has been successfully sent or queued for transmission and the existing connection closed.

Description

The send_file() function sends data from the file associated with the open file handle, directly from the file-system cache, over the connection associated with the socket.

The send_file() function attempts to write header_length bytes from the buffer pointed to by header_data, followed by file_bytes from the file associated with file_descriptor, followed by trailer_length bytes from the buffer pointed to by trailer_data, over the connection associated with the socket pointed to by socket_ptr.

As data is sent, the kernel updates the variables in the sf_parms structure so that if the send_file() is interrupted by a signal, the application simply needs to reissue the send_file(). If the application sets file_offset > the actual file size, or file_bytes > (the actual file size - file_offset), the return value is -1 with errno set to [EINVAL].

The flags argument is effective only after all the data has been sent successfully; otherwise it is ignored. The application should zero the flags argument before setting the appropriate value. If flags = SF_REUSE and socket reuse is not supported, then upon successful completion of sending the data, the kernel closes this socket and sets the socket pointed to by socket_ptr to -1. If flags = SF_CLOSE and send_file() completes successfully, the socket pointed to by socket_ptr is set to -1 by the kernel.

Implementation Note

• The send_file() API can be used only on OS/2 WARP 4.5, which supports Kernel Execution Environment (KEE32), and Installable File System Mechanism (IFSM32). For more information on KEE, refer to OS/2 WARP 4.5 related Document.

• The performance of accept_and_recv() and send_file() is greatly effected by the number of threads that are allowed to be active concurrently. If too few threads are active and work is not done quickly enough, too many threads, needless traps, and context switches can reduce performance by a factor of two. The kernel should make some attempt to intelligently determine how many threads may be active concurrently. Optimally, the number of threads active concurrently should be just below the saturation point, that is, one or two connect request waiting on the backlog queue so that when an accept_and_recv() thread completes, there is another connect requests ready to be processed.

Return Values

There are three possible return values from send_file() :

• An error has occurred, check errno for more information.

• The command has completed successfully.

• The command was interrupted by a signal while sending data.

Error Code

Description
EACCESS
Thecallingprocessdoesnothavetheappropriateprivileges .
EBADF
Eitherthesocketpointedtobythesocket _ ptrargument ,orthefile _ descisnotavaliddescriptor .
ECONNABORTED
Aconnectionhasstopped .
ECONNRESET
Aconnectionwasforciblyclosedbyapeer .
EFAULT
Thedatabufferpointedtobysocket _ ptr ,file _ size ,header _ dataortrailer _ datawasnotvalid .
EINTR
Thesend _ file ( )functionwasinterruptedbyasignalthatwascaughtbeforeanydatawassent .
EINVAL
Thevaluespecifiedbyanattributeisnotvalid .
ENOTCONN
Thesocketisnotconnected .
EPIPE
Thesocketisshutdownforwriting ,orthesocketisconnection - modeandnolongerconnected .
EIO
AnI / Oerroroccurred .
ENETDOWN
Thelocalinterfaceusedtoreachthedestinationisdown .
ENETUNREACH
Noroutetothedestinationispresent .
ENOBUFS
Nobufferspaceisavailable .
ENOMEM
Therewasinsufficientmemoryavailabletocompletetheoperation .
ENOSR
TherewereinsufficientSTREAMSresourcesavailablefortheoperationtocomplete .
ENOTSOCK
Thesocketpointedtobythesocket _ ptrargumentdoesnotrefertoasocket .

Examples

The following is an example of using send_file() call to send a file data over a connected socket.

#define MSG_CLOSE 0x800#define O_RDONLY  0x4

#include #include #include #include #include #include #include #include
char  serveraddress[128],filename[256];
int   serverport = 6000;
int   fd,rc,s;

struct sf_parms
   {
        void   *header_data;      /* ptr to header data */
        size_t header_length;     /* size of header data */
        int    file_handle;       /* file handle to send from */
        size_t file_size;         /* size of file */
        int    file_offset;       /* byte offset in file to send from */
        size_t file_bytes;        /* bytes of file to be sent */
        void   *trailer_data;     /* ptr to trailer data */
        size_t trailer_length;    /* size of trailer data */
        size_t bytes_sent;        /* bytes sent in this send_file call */
   } sfp;

int   putfile (void);

int main (int argc, char *argv[])
{

 strcpy (serveraddress, argv[1]);   /* argv[1] is server address to which file is to be sent */
 strcpy (filename, argv[2]);        /* argv[2] is name of the file to be sent */

 printf ("Sending File to server\n");
   if ((rc = putfile()) != 0)
        {
          printf ("Putfile() failed rc = %d sock_errno = %d \n", rc, sock_errno());
            return(rc);
        }
}

int putfile ()
{
    struct sockaddr_in servername;

    if( (s = socket (PF_INET, SOCK_STREAM, 0)) != -1 )
    {
      servername.sin_len         = sizeof(servername);
      servername.sin_family      = AF_INET;
      servername.sin_addr.s_addr = inet_addr(serveraddress);
      servername.sin_port        = serverport;

    if((rc = connect(s,(struct sockaddr *)&servername,sizeof(servername))) != -1)
       {
            fd =open(filename,O_RDONLY,0);
            sfp.header_data   = 0;
            sfp.header_length = 0;
            sfp.file_handle   = fd;
            sfp.file_size     = -1;
            sfp.file_offset   = 0;
            sfp.file_bytes    = -1;
            sfp.trailer_data  = 0;
            sfp.trailer_length= 0;
            sfp.bytes_sent    = 0;

          if(( rc = send_file(&s,&sfp,MSG_CLOSE)) != 0)
                printf( " ******  FILE NOT SENT  ****** ");
            close(fd);
       }
      else
        printf ("send_file :connect() failed sock_errno = %d \n",sock_errno());
    }
    else
      printf ("send_file :socket() failed rc = %d\n", sock_errno());
   return(rc);
}

Related Calls

send()
connect()
getsockopt()
ioctl()
readv()
recv()
recvfrom()
recvmsg()
select()
sendmsg()
sendto()
setsockopt()
shutdown()
sock_errno()
socket()
writev()

---

[Back: send()]
[Next: sendmsg()]