'\" t .\" Don't change the line above. it tells man that tbl is needed. .\" -*- nroff -*- .\" .\" @(#) $Id: ss7dev.7,v 0.7 2000/10/08 10:18:29 brian Exp $ .\" .\" ========================================================================= .\" .\" This manpage is Copyright (C) 1997, 1998, 1999, 2000 Brian Bidulock. .\" .\" All Rights Reserved. .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Modified $Date: 2000/10/08 10:18:29 $ by $Author: brian $ .\" .\" ========================================================================= .\" .\" $Log: ss7dev.7,v $ .\" Revision 0.7 2000/10/08 10:18:29 brian .\" Added man pages. .\" .\" ========================================================================= .TH SS7DEV 7 "7 October 2000" "Linux Man Page" "Linux Programmer's Manual" .SH NAME ss7dev \- Low level access to OpenSS7 SS7 MTP Level 2 (Link) Devices .SH SYNOPSIS .in +0.5i .B #include .br .B #include .SH DESCRIPTION .PP This man page describes the sockets interface which is used to configure SS7 Link interface devices. .PP OpenSS7 supports some standards ioctls to configure SS7 Link level devices. They can be used on any SS7 socket, regardless of the family, protocol or socket type. They pass an .B ifreq structure. .sp 1 .in +0.5i .nf struct ifreq { char ifr_name[IFNAMSIZE]; /* Interface name */ union { struct sockaddr ifr_addr; struct sockaddr ifr_dstaddr; struct sockaddr ifr_broadcast; struct sockaddr ifr_netmask; struct sockaddr ifr_hwaddr; short ifr_flags; int ifr_ifindex; int ifr_metric; int ifr_mtu; struct ifmap ifr_map; char ifr_slave[IFNAMSIZ]; char ifr_newname[IFNAMSIZ]; char * ifr_data; }; } struct ifconf { int ifc_len; /* size of buffer */ union { char * ifc_buf; /* buffer address */ struct ifreq * ifc_req; /* array of structures */ }; }; .fi .PP Normally, the user specifies which device to affect by setting .B ifr_name to the name of the interface. All other members of the stucture man share memory. .SH "ADDRESS FORMATS" .PP Addresses (SS7 Point Codes) are formatted as described in .BR ss7 (7). .SH "SYSCTLS" .PP These sysctls can be accessed by the .B /proc/sys/net/ss7/link/* files or with the .BR sysctl (2) interface. .TP 0.5i .B ss7_link_pcr When this sysctl is enabled, the SS7 Link will perform PCR (Preventative Cyclic Retransmission) procedures for transmission and reception as described in ITU-T Q.703, ANSI T1.111 and ETS ETS 300 008. Otherwise, the link uses the default Basic procedures. .SH "SOCKET OPTIONS" .PP There are no device specific socket options. For SS7 socket options applicable to SS7 sockets, see .BR ss7 (7); for SS7 link specific options, see .BR link (7). .SH "IOCTLS" .PP If an ioctl is marked as privileged, then using it requires an effective user id of 0 or the .B CAP_NET_ADMIN capability. If this is not the case .B EPERM will be returned. .TP 0.5i .B SIOCGIFNAME Given the .BR ifr_ifindex , return the name of the interface in .BR ifr_name . This is the only ioctl which returns its result in .BR ifr_name . .TP .B SIOCGIFINDEX Retreive the interface index of the interface into .BR ifr_ifindex . .TP .B SIOCSIFNAME Changes the name of the interface specified in .BR ifr_ifindex " to " ifr_ifnewname . This is a privileged operation. .TP .BR SIOCGIFADDR ", " SIOCSIFADDR Gets or sets the interface address for the device using .BR ifr_addr . For an SS7 device, this sets the .I local MTP PC (Point Code) associated with the link. The interface address can only be set on a link which is out-of-service. .TP .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR Gets or sets the destination address for the device using .BR ifr_dstaddr . For an SS7 device, this sets the .I adjacent MTP PC (Point Code) associated with the link. The destination address can only be set on a link which is out-of-service. .TP .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS Get or set the active flags word of the device, .B ifr_flags contains a bit mask of the following values (some values are preset for SS7 vs. IP, and some values are not applicable): .RS .in +8 .TP 20 IFF_UP - Interface is running. .br Used normally (similar to IP) for SS7. .TP IFF_BROADCAST - Valid broadcast address set. .br Not used for SS7; always set false (0). .TP IFF_DEBUG - Internal debugging flag. .br Used normally (similar to IP) for SS7. .TP IFF_LOOPBACK - Interface is a loopback interface. .br Not used for SS7; always set false (0). .TP IFF_POINTTOPOINT - Interface is a point-to-point link. .br Not used for SS7; always set to true (1). .TP IFF_RUNNING - Resources allocated. .br Used normally (similar to IP) for SS7. .TP IFF_NOARP - No arp protocol, L2 destination address not set. .br Not used for SS7; always set false (0). .TP IFF_PROMISC - Interface is in promiscuous mode. .br Not used for SS7; always set false (0). .TP IFF_NOTRAILERS - Avoid use of trailers. .br Not used for SS7; always set true (1). .TP IFF_ALLMULTI - Received all multicast packets. .br Not used for SS7; always set false (0). .TP IFF_MASTER - Master of a load balancing bundle. .br Not used for SS7; always set false (0). .TP IFF_SLAVE - Slave of a load balancing bundle. .br Not used for SS7; always set false (0). .TP IFF_MULTICAST - Supports multicast. .br Not used for SS7; always set false (0). .TP IFF_PORTSEL - Is able to select media type via ifmap. .br Not used for SS7 .TP IFF_AUTOMEDIA - Auto media selection active. .br Not used for SS7; always set false (0). .TP IFF_DYNAMIC - The addresses are lost when the interface goes down. .br Not used for SS7; always set false (0). .in -8 .RE .IP "" 0.5i Setting the active flag word is a privileged operation, but any process may read it. .TP .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC Get or set the metric of the device using .BR ifr_metric . This is currently not implemented; it sets .B ifr_metric to 0 of you attempt to read it and returns .B EINVAL if you attempt to set it. Eventually this will be used to set a SDT (Signalling Data Terminal) priority. .TP .BR SIOCGIFMTU ", "SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit), or, in SS7 terms, the SIF_MAX of a device using .BR ifr_mtu . Setting the MTU is a privileged operation. Setting the MTU to other than a standard value for the interface (LSL, HSL) will cause non-conforming operation of the interface for SS7. .TP .BR SIOCGIFMAP ", " SIOCSIFMAP Get or set the interface hardware parameters using .BR ifr_map . Setting the paramters is a privileged operation. .sp 1 .in +0.5i .nf struct ifmap { unsigned long mem_start; unsigned long mem_end; unsigned short base_addr; unsigned char irq; unsigned char dma; unsigned char port; }; .fi .in -0.5i The interpretation of the ifmap structure depends on the device driver and the architecture. .TP .BR SIOCGIFXQLEN ", " SIOCSIFXQLEN Get or set the transmit queue length of a device using .BR ifr_qlen . Setting the transmit queue length is a privileged operation. .TP .B SIOCGIFCONF Return a list of interface (transport layer) addresses. The user passes an .B ifconf stucture as an argumnent to the ioctl. It contains a pointer to an array of .I ifreq structures in .B ifc_req and it length in bytes is .BR ifc_len . The kernel fills the ifreqs with all current L3 interface addresses that are running: .I ifr_name contains the interface name (ss7link0, etc), .I ifr_addr the address. The kernel returns with the actual length in .IR ifr_len ; if it is equal to the original length, the user should assume that it overflowed and retry with a bigger buffer. When no error occurs, the ioctl returns 0; otherwise -1. Overflow is no error. .PP The following ioctls do not use the .B ifreq structure: .TP .BR SS7IOCIFINHIBIT ", " SS7IOCIFUNIHIBIT Inhibits or unihibits the SDL (Signalling Data Link) associated with this SDT (Signalling Data Terminal). This is a pivileged operation. .PP Most protocols support their own ioctls to configure protocol specific interface options. See the protocol man pages for description. For configuring MTP Point Codes (PCs), see .BR mtp (7). .PP In addition, some devices support private ioctls. These are not described here. \".SH "ERROR HANDLING" .SH "ERRORS" .TP .B EADDRNOTAVAIL The requested address is not available. This error is returned in response to .B SIOCSIFADDR when the .I local PC (Point Code) does not exist locally; it is also returned for .B SIOCSIFDSTADDR for a missing .I adjacent PC (Point Code). One could use the .B SIOCADDRT ioctl to add the missing address. .TP .B EACCES The operation is a privileged operation and the caller does not have sufficient access permissions or capabilities to perform the operation. .TP .B EINVAL A parameter is invalid. .TP .B EFAULT A system fault occured. .TP .B EPERM The caller does not have permission to execute the operation on the socket descriptor. \".SH "EXAMPLES" .SH "SEE ALSO" .BR ss7 "(7), " link "(7), " mtp "(7), " packet "(7), " proc "(7), " netdevice "(7), " sysctl "(2)." .SH "NOTES" .PP Many of the ioctls which are available for .BR netdevice (7) are .BR ip (7) specific and are not applicable. .PP The names of interfaces with no addresses or that don't have the .B IFF_RUNNING flag set can be found via .BR /proc/net/ss7/dev . \".SH "CAVEATS" \".SH "DIAGNOSTICS" .SH "BUGS" .PP As this is an ALPHA (experimental) release. As such, there are probably many .I unknown bugs. The SS7 LINK interface is not capable of performing PCR (Preventative Cyclic Restransmission) procedures and the .B ss7_link_pcr sysctl has no effect. .SH "RESTRICTIONS" .PP The SS7 LINK interface does not currently support the concept of dynamic assignment of Signalling Data Terminals as described in ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008. Each Signalling Data Terminal (ss7 device) is bound to a Signalling Data Link (communications path between signalling points). .SH "AUTHOR" .PP Brian F. G. Bidulock, .IR "" "<" bidulock@openswitch.org ">." .PP This man page borrows literally and heavily from the .BR netdevice (7) man page for Linux written by Andi Kleen .IR "" "<" ak@muc.de ">." .SH "HISTORY" .PP OpenSS7 is a kernel module for Linux written for the Linux 2.2 kernel. .SH "REFERENCES" .nf ITU-T Rec. Q.700, Introduction to CCITT Signalling System No. 7, ITU-T Rec. Q.701, Functional description of the MTP, ITU-T Rec. Q.702, Signalling data link, ITU-T Rec. Q.703, Signalling link, ITU-T Rec. Q.704, Signalling network functions and messages. .fi .nf ANSI T1.110, General Information, ANSI T1.111, Message Transfer Part (MTP). .fi .nf ETSI ETS 300 008-1, Message Transfer Part (MTP), ETSI ETS 300 008-2, Message Transfer Part (MTP). .fi