documented socket usage